Also when there is both a docstring and directive-level content put
the docstring first. That seems to match what Sphinx's autodoc does
and looks less odd.
Possible future improvement: a parameter to suppress the docstring?
Possibly a way to reorder the non-docstring content (e.g. members
documentation)?
With more than 1 level of generic type, the "closure" of generic
parameters would get tokenized by python as a single right shift (>>)
rather than two gt (>, >) leading to our own tokenizing pass getting
lost and blowing up.
Fix by explicitly recognizing and splitting (>>) into (>, >). We could
consider writing the entire tokenizer ourselves instead of
post-processing Python's but given the entire post-processing function
is currently shorter than just Pythons' tokenizer's regexes...
Anyway issue found by vsc while trying to write better docstrings.
Revert 6cb12273e2 which reverted
08d48b0fff.
Issue was the support for sub-parameters (aka @param {type} foo.bar)
where the "parent" parameter was not formal (only present in a
function's docstring, but not in the function's parameters list),
subtype creation would fail to find a root parameter to attach the
sub-parameter to.
This has not actually been fixed, but for the specific case where the
formal parameters list is *completely empty* we fall back on a list of
the docstring's parameters, which works well enough for this case.
Before this, if a new global was added to JS code (module toplevel,
function bodies are not considered) it would blow up when attempting
to resolve variable refs & uses.
Make the toplevel scope a defaultdict such that if e.g. a "foo" is
looked up in a module but not a local variable of that module it's
assumed to be an UnknownNS object (from which further UnknownNS can be
deref'd).
* fix P3 incompatibilities in doc/_extensions
* vendor pyjsdoc, strip out everything we're not using and make what's
left P3-compatible (upstream is not P3 compliant)
* drop undeclared dependency on attrs as it turns out not to be much
used
* Fix a bunch of ill-documented/incomplete/incorrect method docs
* add start of Sphinx extension to extract & integrate jsdoc into
Sphinx documentation:
- parse JS files (and don't blow up), uses a fork of pyjsparser as
the project currently does not parse comments
- extract cross-module dependency information
- parse JsDoc comments using pyjsdoc and infer structure from code &
jsdoc
- ``ast`` CLI printing a simplified AST of the input files
- ``dependencies`` creating a dependency graph of either all modules
in the provided input files or the modules matching the specified
filters (warning: will not work if missing dependencies),
generates a .dot file
- ``extractor`` generating a plain text module documentation (mix of
rst and markdown styles, not anything formal)
* sphinx extension with an "automodule" directive taking a module name
and generating the documentation for it
Xavier Morel