=========
sphinx-js
=========
Why
===
When you write a JavaScript library, how do you explain it to people? If it's a small project in a domain your users are familiar with, JSDoc's alphabetical list of routines might suffice. But in a larger project, it is useful to intersperse prose with your API docs without having to copy and paste things.
sphinx-js lets you use the industry-leading `Sphinx <http://sphinx-doc.org/>`_ documentation tool with JS projects. It provides a handful of directives, patterned after the Python-centric `autodoc <www.sphinx-doc.org/en/latest/ext/autodoc.html>`_ ones, for pulling JSDoc-formatted documentation into reStructuredText pages. And, because you can keep using JSDoc in your code, you remain compatible with the rest of your JS tooling, like Google's Closure Compiler.
sphinx-js also works with TypeScript, using the TypeDoc tool in place of JSDoc and emitting all the type information you would expect.
Setup
=====
1. Install JSDoc (or TypeDoc if you're writing TypeScript). The tool must be on your ``$PATH``, so you might want to install it globally::
npm install -g jsdoc
...or... ::
npm install -g typedoc
JSDoc 3.6.3 and 4.0.0 and TypeDoc 0.15.0 are known to work.
2. Install sphinx-js, which will pull in Sphinx itself as a dependency::
pip install sphinx-js
3. Make a documentation folder in your project by running ``sphinx-quickstart`` and answering its questions::
cd my-project
sphinx-quickstart
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Selected root path: .
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]:
The project name will occur in several places in the built documentation.
> Project name: My Project
> Author name(s): Fred Fredson
> Project release []: 1.0
If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.
For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]:
4. In the generated Sphinx conf.py file, turn on ``sphinx_js`` by adding it to ``extensions``::
extensions = ['sphinx_js']
5. If you want to document TypeScript, add ``js_language = 'typescript'`` to conf.py as well.
6. If your JS source code is anywhere but at the root of your project, add ``js_source_path = '../somewhere/else'`` on a line by itself in conf.py. The root of your JS source tree should be where that setting points, relative to the conf.py file. (The default, ``../``, works well when there is a ``docs`` folder at the root of your project and your source code lives directly inside the root.)
7. If you have special JSDoc or TypeDoc configuration, add ``jsdoc_config_path = '../conf.json'`` (for example) to conf.py as well.
8. If you're documenting only JS or TS and no other languages (like C), you can set your "primary domain" to JS in conf.py::
primary_domain = 'js'
(The domain is ``js`` even if you're writing TypeScript.) Then you can omit all the "js:" prefixes in the directives below.
Use
===
In short, in a Sphinx project, use the following directives to pull in your JSDoc documentation, then tell Sphinx to render it all by running ``make html`` in your docs directory. If you have never used Sphinx or written reStructuredText before, here is `where we left off in its tutorial <http://www.sphinx-doc.org/en/stable/tutorial.html#defining-document-structure>`_. For a quick start, just add things to index.rst until you prove things are working.
autofunction
------------
First, document your JS code using standard JSDoc formatting::
/**
* Return the ratio of the inline text length of the links in an element to
* the inline text length of the entire element.
*
* @param {Node} node - Types or not: either works.
* @throws {PartyError|Hearty} Multiple types work fine.
* @returns {Number} Types and descriptions are both supported.
*/
function linkDensity(node) {
const length = node.flavors.get('paragraphish').inlineLength;
const lengthWithoutLinks = inlineTextLength(node.element,
element => element.tagName !== 'A');
return (length - lengthWithoutLinks) / length;
}
Then, reference your documentation using sphinx-js directives. Our directives work much like Sphinx's standard autodoc ones. You can specify just a function's name... ::
.. js:autofunction:: someFunction
...and a nicely formatted block of documentation will show up in your docs.
You can also throw in your own explicit parameter list, if you want to note
optional parameters::
.. js:autofunction:: someFunction(foo, bar[, baz])
Parameter properties and destructuring parameters also work fine, using `standard JSDoc syntax <https://jsdoc.app/tags-param.html#parameters-with-properties>`_::
/**
* Export an image from the given canvas and save it to the disk.
*
* @param {Object} options Output options
* @param {string} options.format The output format (``jpeg``, ``png``, or
* ``webp``)
* @param {number} options.quality The output quality when format is
* ``jpeg`` or ``webp`` (from ``0.00`` to ``1.00``)
*/
function saveCanvas({ format, quality }) {
// ...
}
Extraction of default parameter values works as well. These act as expected, with a few caveats::
/**
* You must declare the params, even if you have nothing else to say, so
* JSDoc will extract the default values.
*
* @param [num]
* @param [str]
* @param [bool]
* @param [nil]
*/
function defaultsDocumentedInCode(num=5, str="true", bool=true, nil=null) {}
/**
* JSDoc guesses types for things like "42". If you have a string-typed
* default value that looks like a number or boolean, you'll need to
* specify its type explicitly. Conversely, if you have a more complex
* value like an arrow function, specify a non-string type on it so it
* isn't interpreted as a string. Finally, if you have a disjoint type like
* {string|Array} specify string first if you want your default to be
* interpreted as a string.
*
* @param {function} [func=() => 5]
* @param [str=some string]
* @param {string} [strNum=42]
* @param {string|Array} [strBool=true]
* @param [num=5]
* @param [nil=null]
*/
function defaultsDocumentedInDoclet(func, strNum, strBool, num, nil) {}
You can even add additional content. If you do, it will appear just below any extracted documentation::
.. js:autofunction:: someFunction
Here are some things that will appear...
* Below
* The
* Extracted
* Docs
Enjoy!
``js:autofunction`` has one option, ``:short-name:``, which comes in handy for chained APIs whose implementation details you want to keep out of sight. When you use it on a class method, the containing class won't be mentioned in the docs, the function will appear under its short name in indices, and cross references must use the short name as well (``:func:`someFunction```)::
.. js:autofunction:: someClass#someFunction
:short-name:
``autofunction`` can also be used on callbacks defined with the `@callback tag <https://jsdoc.app/tags-callback.html>`_.
There is experimental support for abusing ``autofunction`` to document `@typedef tags <https://jsdoc.app/tags-typedef.html>`_ as well, though the result will be styled as a function, and ``@property`` tags will fall misleadingly under an "Arguments" heading. Still, it's better than nothing until we can do it properly.
autoclass
---------
We provide a ``js:autoclass`` directive which documents a class with the concatenation of its class comment and its constructor comment. It shares all the features of ``js:autofunction`` and even takes the same ``:short-name:`` flag, which can come in handy for inner classes. The easiest way to use it is to invoke its ``:members:`` option, which automatically documents all your class's public methods and attributes::
.. js:autoclass:: SomeEs6Class(constructor, args, if, you[, wish])
:members:
You can add private members by saying... ::
.. js:autoclass:: SomeEs6Class
:members:
:private-members:
Privacy is determined by JSDoc ``@private`` tags or TypeScript's ``private`` keyword.
Exclude certain members by name with ``:exclude-members:``::
.. js:autoclass:: SomeEs6Class
:members:
:exclude-members: Foo, bar, baz
Or explicitly list the members you want. We will respect your ordering. ::
.. js:autoclass:: SomeEs6Class
:members: Qux, qum
When explicitly listing members, you can include ``*`` to include all unmentioned members. This is useful to have control over ordering of some elements, without having to include an exhaustive list. ::
.. js:autoclass:: SomeEs6Class
:members: importMethod, *, uncommonlyUsedMethod
Finally, if you want full control, pull your class members in one at a time by embedding ``js:autofunction`` or ``js:autoattribute``::
.. js:autoclass:: SomeEs6Class
.. js:autofunction:: SomeEs6Class#someMethod
Additional content can go here and appears below the in-code comments,
allowing you to intersperse long prose passages and examples that you
don't want in your code.
autoattribute
-------------
This is useful for documenting public properties::
class Fnode {
constructor(element) {
/**
* The raw DOM element this wrapper describes
*/
this.element = element;
}
}
And then, in the docs... ::
.. autoclass:: Fnode
.. autoattribute:: Fnode#element
This is also the way to document ES6-style getters and setters, as it omits the trailing ``()`` of a function. The assumed practice is the usual JSDoc one: document only one of your getter/setter pair::
class Bing {
/** The bong of the bing */
get bong() {
return this._bong;
}
set bong(newBong) {
this._bong = newBong * 2;
}
}
And then, in the docs... ::
.. autoattribute:: Bing#bong
Dodging Ambiguity With Pathnames
--------------------------------
If you have same-named objects in different files, use pathnames to disambiguate them. Here's a particularly long example::
.. js:autofunction:: ./some/dir/some/file.SomeClass#someInstanceMethod.staticMethod~innerMember
You may recognize the separators ``#.~`` from `JSDoc namepaths <https://jsdoc.app/about-namepaths.html>`_; they work the same here.
For conciseness, you can use any unique suffix, as long as it consists of complete path segments. These would all be equivalent to the above, assuming they are unique within your source tree::
innerMember
staticMethod~innerMember
SomeClass#someInstanceMethod.staticMethod~innerMember
some/file.SomeClass#someInstanceMethod.staticMethod~innerMember
Things to note:
* We use simple file paths rather than JSDoc's ``module:`` prefix or TypeDoc's ``external:`` or ``module:`` ones.
* We use simple backslash escaping exclusively rather than switching escaping schemes halfway through the path; JSDoc itself `is headed that way as well <https://github.com/jsdoc3/jsdoc/issues/876>`_. The characters that need to be escaped are ``#.~(/``, though you do not need to escape the dots in a leading ``./`` or ``../``. A really horrible path might be... ::
some/path\ with\ spaces/file.topLevelObject#instanceMember.staticMember\(with\(parens
* Relative paths are relative to the ``js_source_path`` specified in the config. Absolute paths are not allowed.
Behind the scenes, sphinx-js will change all separators to dots so that...
* Sphinx's "shortening" syntax works: ``:func:`~InwardRhs.atMost``` prints as merely ``atMost()``. (For now, you should always use dots rather than other namepath separators: ``#~``.)
* Sphinx indexes more informatively, saying methods belong to their classes.
Saving Keystrokes By Setting The Primary Domain
-----------------------------------------------
To save some keystrokes, you can set ``primary_domain = 'js'`` in conf.py and then say (for example) ``autofunction`` rather than ``js:autofunction``.
TypeScript: Getting Superclass and Interface Links To Work
----------------------------------------------------------
To have a class link to its superclasses and implemented interfaces, you'll need to document the superclass (or interface) somewhere using ``js:autoclass`` or ``js:class`` and use the class's full (but dotted) path when you do::
.. js:autoclass:: someFile.SomeClass
Unfortunately, Sphinx's ``~`` syntax doesn't work in these spots, so users will see the full paths in the documentation.
Configuration Reference
-----------------------
``js_language``
Use 'javascript' or 'typescript' depending on the language you use. The default is 'javascript'.
``js_source_path``
A list of directories to scan (non-recursively) for JS or TS source files, relative to Sphinx's conf.py file. Can be a string instead if there is only one. If there is more than one, ``root_for_relative_js_paths`` must be specified as well. Defaults to '../'.
``jsdoc_config_path``
A conf.py-relative path to a JSDoc config file, which is useful if you want to specify your own JSDoc options, like recursion and custom filename matching. If using TypeDoc, you can also point to a ``tsconfig.json`` file.
``root_for_relative_js_paths``
Relative JS entity paths are resolved relative to this path. Defaults to ``js_source_path`` if it is only one item.
``jsdoc_cache``
Path to a file where JSDoc output will be cached. If omitted, JSDoc will be run every time Sphinx is. If you have a large number of source files, it may help to configure this value. But be careful: the cache is not automatically flushed if your source code changes; you must delete it manually.
Example
=======
A good example using most of sphinx-js's functionality is the Fathom documentation. A particularly juicy page is https://mozilla.github.io/fathom/ruleset.html. Click the "View page source" link to see the raw directives.
`ReadTheDocs <https://readthedocs.org/>`_ is the canonical hosting platform for Sphinx docs and now supports sphinx-js as an opt-in beta. Put this in the ``.readthedocs.yml`` file at the root of your repo::
requirements_file: docs/requirements.txt
build:
image: latest
Then put the version of sphinx-js you want in ``docs/requirements.txt``. For example... ::
sphinx-js==3.1.2
Or, if you prefer, the Fathom repo carries a `Travis CI configuration <https://github.com/mozilla/fathom/blob/92304b8ad4768e90c167c3d93f9865771f5a6d80/.travis.yml#L41>`_ and a `deployment script <https://github.com/mozilla/fathom/blob/92304b8ad4768e90c167c3d93f9865771f5a6d80/tooling/travis-deploy-docs>`_ for building docs with sphinx-js and publishing them to GitHub Pages. Feel free to borrow them.
Caveats
=======
* We don't understand the inline JSDoc constructs like ``{@link foo}``; you have to use Sphinx-style equivalents for now, like ``:js:func:`foo``` (or simply ``:func:`foo``` if you have set ``primary_domain = 'js'`` in conf.py.
* So far, we understand and convert the JSDoc block tags ``@param``, ``@returns``, ``@throws``, ``@example`` (without the optional ``<caption>``), ``@deprecated``, ``@see``, and their synonyms. Other ones will go *poof* into the ether.
Tests
=====
Run the tests using tox, which will also install JSDoc and TypeDoc at pinned versions::
pip install tox
tox
Version History
===============
3.2.2: (September 20th, 2023)
* Remove Sphinx upper-bound requirement. (#227)
* Drop support for Python 3.7. (#228)
Thank you to Will Kahn-Greene!
3.2.1: (December 16th, 2022)
* Fix xrefs to static functions. (#178)
* Add support for jsdoc 4.0.0. (#215)
Thank you to xsjad0 and Will Kahn-Greene!
3.2.0: (December 13th, 2022)
* Add "static" in front of static methods.
* Pin Jinja2 and markupsafe versions. (#190)
* Track dependencies; do not read all documents. This improves speed of incremental updates. (#194)
* Support Python 3.10 and 3.11. (#186)
* Support Sphinx >= 4.1.0. (#209)
* Fix types warning for ``js_source_path`` configuration item. (#182)
Thank you Stefan 'hr' Berder, David Huggins-Daines, Nick Alexander, mariusschenzle, Erik Rose, lonnen, and Will Kahn-Greene!
3.1.2: (April 15th, 2021)
* Remove our declared dependency on ``docutils`` to work around the way pip's greedy dependency resolver reacts to the latest version of Sphinx. pip fails when pip-installing sphinx-js because pip sees our "any version of docutils" declaration first (which resolves greedily to the latest version, 0.17) but later encounters Sphinx's apparently new ``<0.17`` constraint and gives up. We can revert this when pip's ``--use-feature=2020-resolver`` becomes the default.
3.1.1: (March 23rd, 2021)
* Rewrite large parts of the suffix tree that powers path lookup. This fixes several crashers.
3.1: (September 10th, 2020)
* Re-architect language analysis. There is now a well-documented intermediate representation between JSDoc- and TypeDoc-emitted JSON and the renderers. This should make it much faster to merge PRs.
* Rewrite much of the TypeScript analysis engine so it feeds into the new IR.
* TypeScript analysis used to crash if your codebase contained any overloaded functions. This no longer happens; we now arbitrarily use only the first function signature of each overloaded function.
* Add support for static properties on TS classes.
* Support variadic args in TS.
* Support intersection types (``foo & bar``) in TS.
* Remove the "exported from" module links from classes and interfaces. Functions never had them. Let's see if we miss them.
* Pathnames for TypeScript objects no longer spuriously use ``~`` after the filename path segment; now they use ``.`` as in JS.
* More generally, TS pathnames are now just like JS ones. There is no more ``external:`` prefix in front of filenames or ``module:`` in front of namespace names.
* TS analyzer no longer cares with the current working directory is.
* Tests now assert only what they care about rather than being brittle to the point of prohibiting any change.
* No longer show args in the arg list that are utterly uninformative, lacking both description and type info.
* Class attributes are now listed before methods unless manally ordered with ``:members:``.
3.0.1: (August 10th, 2020)
* Don't crash when encountering a ``../`` prefix on an object path. This can happen behind the scenes when ``root_for_relative_js_paths`` is set inward of the JS code.
3.0: (July 14th, 2020)
* Make compatible with Sphinx 3, which requires Python 3.
* Drop support for Python 2.
* Make sphinx-js not care what the current working directory is, except for the TypeScript analyzer, which needs further work.
* Properly RST-escape return types.
2.8: (September 16th, 2019)
* Display generic TypeScript types properly. Make fields come before methods. (Paul Grau)
* Combine constructor and class documentation at the top TypeScript classes. (Sebastian Weigand)
* Switch to pytest as the testrunner. (Sebastian Weigand)
* Add optional caching of JSDoc output, for large codebases. (Patrick Browne)
* Fix the display of union types in TypeScript. (Sebastian Weigand)
* Fix parsing breakage that began in typedoc 0.14.0. (Paul Grau)
* Fix a data-intake crash with TypeScript. (Cristiano Santos)
2.7.1: (November 16th, 2018)
* Fix a crash that would happen sometimes with UTF-8 on Windows. #67.
* Always use conf.py's dir for JSDoc's working dir. #78. (Thomas Khyn)
2.7: (August 2nd, 2018))
* Add experimental TypeScript support. (Wim Yedema)
2.6: (July 26th, 2018)
* Add support for ``@deprecated`` and ``@see``. (David Li)
* Notice and document JS variadic params nicely. (David Li)
* Add linter to codebase.
2.5: (April 20th, 2018)
* Use documented ``@params`` to help fill out the formal param list for a
function. This keeps us from missing params that use destructuring. (flozz)
* Improve error reporting when JSDoc is missing.
* Add extracted default values to generated formal param lists. (flozz and erikrose)
2.4: (March 21, 2018)
* Support the ``@example`` tag. (lidavidm)
* Work under Windows. Before, we could hardly find any documentation. (flozz)
* Properly unwrap multiple-line JSDoc tags, even if they have Windows line endings. (Wim Yedema)
* Drop support for Python 3.3, since Sphinx has also done so.
* Fix build-time crash when using recommonmark (for Markdown support) under Sphinx >=1.7.1. (jamrizzi)
2.3.1: (January 11th, 2018)
* Find the ``jsdoc`` command on Windows, where it has a different name. Then
patch up process communication so it doesn't hang.
2.3: (November 1st, 2017)
* Add the ability to say "*" within the ``autoclass :members:`` option, meaning "and all the members that I didn't explicitly list".
2.2: (October 10th, 2017)
* Add ``autofunction`` support for ``@callback`` tags. (krassowski)
* Add experimental ``autofunction`` support for ``@typedef`` tags. (krassowski)
* Add a nice error message for when JSDoc can't find any JS files.
* Pin six more tightly so ``python_2_unicode_compatible`` is sure to be around.
2.1: (August 30th, 2017)
* Allow multiple folders in ``js_source_path``. This is useful for gradually migrating large projects, one folder at a time, to JSDoc. Introduce ``root_for_relative_js_paths`` to keep relative paths unambiguous in the face of multiple source paths.
* Aggregate PathTaken errors, and report them all at once. This means you don't have to run JSDoc repeatedly while cleaning up large projects.
* Fix a bytes-vs-strings issue that crashed on versions of Python 3 before 3.6. (jhkennedy)
* Tolerate JS files that have filename extensions other than ".js". Before, when combined with custom JSDoc configuration that ingested such files, incorrect object pathnames were generated, which led to spurious "No JSDoc documentation was found for object ..." errors.
2.0.1: (July 13th, 2017)
* Fix spurious syntax errors while loading large JSDoc output by writing it to a temp file first. (jhkennedy)
2.0: (May 4th, 2017)
* Deal with ambiguous object paths. Symbols with identical JSDoc longnames (such as two top-level things called "foo" in different files) will no longer have one shadow the other. Introduce an unambiguous path convention for referring to objects. Add a real parser to parse them rather than the dirty tricks we were using before. Backward compatibility breaks a little, because ambiguous references are now a fatal error, rather than quietly referring to the last definition JSDoc happened to encounter.
* Index everything into a suffix tree so you can use any unique path suffix to refer to an object.
* Other fallout of having a real parser:
* Stop supporting "-" as a namepath separator.
* No longer spuriously translate escaped separators in namepaths into dots.
* Otherwise treat paths and escapes properly. For example, we can now handle symbols that contain "(".
* Fix KeyError when trying to gather the constructor params of a plain old
object labeled as a ``@class``.
1.5.2: (March 22th, 2017)
* Fix crasher while warning that a specified longname isn't found.
1.5.1: (March 20th, 2017)
* Sort ``:members:`` alphabetically when an order is not explicitly specified.
1.5: (March 17th, 2017)
* Add ``:members:`` option to ``autoclass``.
* Add ``:private-members:`` and ``:exclude-members:`` options to go with it.
* Significantly refactor to allow directive classes to talk to each other.
1.4: (March 10th, 2017)
* Add ``jsdoc_config_path`` option.
1.3.1: (March 6th, 2017)
* Tolerate @args and other info field lines that are wrapped in the source code.
* Cite the file and line of the source comment in Sphinx-emitted warnings and errors.
1.3: (February 21st, 2017)
* Add ``autoattribute`` directive.
1.2: (February 14th, 2017)
* Always do full rebuilds; don't leave pages stale when JS code has changed but the RSTs have not.
* Make Python-3-compatible.
* Add basic ``autoclass`` directive.
1.1: (February 13th, 2017)
* Add ``:short-name:`` option.
1.0: (February 7th, 2017)
* Initial release, with just ``js:autofunction``
Raw data
{
"_id": null,
"home_page": "https://github.com/mozilla/sphinx-js",
"name": "sphinx-js",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "sphinx,documentation,docs,javascript,js,jsdoc,restructured,typescript,typedoc",
"author": "Erik Rose",
"author_email": "erikrose@grinchcentral.com",
"download_url": "https://files.pythonhosted.org/packages/51/a2/0d8bc324e43e85bdb256a716af23348a01bb5e58d0b5540745d52ef2edc9/sphinx-js-3.2.2.tar.gz",
"platform": null,
"description": "=========\nsphinx-js\n=========\n\nWhy\n===\n\nWhen you write a JavaScript library, how do you explain it to people? If it's a small project in a domain your users are familiar with, JSDoc's alphabetical list of routines might suffice. But in a larger project, it is useful to intersperse prose with your API docs without having to copy and paste things.\n\nsphinx-js lets you use the industry-leading `Sphinx <http://sphinx-doc.org/>`_ documentation tool with JS projects. It provides a handful of directives, patterned after the Python-centric `autodoc <www.sphinx-doc.org/en/latest/ext/autodoc.html>`_ ones, for pulling JSDoc-formatted documentation into reStructuredText pages. And, because you can keep using JSDoc in your code, you remain compatible with the rest of your JS tooling, like Google's Closure Compiler.\n\nsphinx-js also works with TypeScript, using the TypeDoc tool in place of JSDoc and emitting all the type information you would expect.\n\nSetup\n=====\n\n1. Install JSDoc (or TypeDoc if you're writing TypeScript). The tool must be on your ``$PATH``, so you might want to install it globally::\n\n npm install -g jsdoc\n\n ...or... ::\n\n npm install -g typedoc\n\n JSDoc 3.6.3 and 4.0.0 and TypeDoc 0.15.0 are known to work.\n\n2. Install sphinx-js, which will pull in Sphinx itself as a dependency::\n\n pip install sphinx-js\n\n3. Make a documentation folder in your project by running ``sphinx-quickstart`` and answering its questions::\n\n cd my-project\n sphinx-quickstart\n\n Please enter values for the following settings (just press Enter to\n accept a default value, if one is given in brackets).\n\n Selected root path: .\n\n You have two options for placing the build directory for Sphinx output.\n Either, you use a directory \"_build\" within the root path, or you separate\n \"source\" and \"build\" directories within the root path.\n > Separate source and build directories (y/n) [n]:\n\n The project name will occur in several places in the built documentation.\n > Project name: My Project\n > Author name(s): Fred Fredson\n > Project release []: 1.0\n\n If the documents are to be written in a language other than English,\n you can select a language here by its language code. Sphinx will then\n translate text that it generates into that language.\n\n For a list of supported codes, see\n https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.\n > Project language [en]:\n\n4. In the generated Sphinx conf.py file, turn on ``sphinx_js`` by adding it to ``extensions``::\n\n extensions = ['sphinx_js']\n\n5. If you want to document TypeScript, add ``js_language = 'typescript'`` to conf.py as well.\n6. If your JS source code is anywhere but at the root of your project, add ``js_source_path = '../somewhere/else'`` on a line by itself in conf.py. The root of your JS source tree should be where that setting points, relative to the conf.py file. (The default, ``../``, works well when there is a ``docs`` folder at the root of your project and your source code lives directly inside the root.)\n7. If you have special JSDoc or TypeDoc configuration, add ``jsdoc_config_path = '../conf.json'`` (for example) to conf.py as well.\n8. If you're documenting only JS or TS and no other languages (like C), you can set your \"primary domain\" to JS in conf.py::\n\n primary_domain = 'js'\n\n (The domain is ``js`` even if you're writing TypeScript.) Then you can omit all the \"js:\" prefixes in the directives below.\n\nUse\n===\n\nIn short, in a Sphinx project, use the following directives to pull in your JSDoc documentation, then tell Sphinx to render it all by running ``make html`` in your docs directory. If you have never used Sphinx or written reStructuredText before, here is `where we left off in its tutorial <http://www.sphinx-doc.org/en/stable/tutorial.html#defining-document-structure>`_. For a quick start, just add things to index.rst until you prove things are working.\n\nautofunction\n------------\n\nFirst, document your JS code using standard JSDoc formatting::\n\n /**\n * Return the ratio of the inline text length of the links in an element to\n * the inline text length of the entire element.\n *\n * @param {Node} node - Types or not: either works.\n * @throws {PartyError|Hearty} Multiple types work fine.\n * @returns {Number} Types and descriptions are both supported.\n */\n function linkDensity(node) {\n const length = node.flavors.get('paragraphish').inlineLength;\n const lengthWithoutLinks = inlineTextLength(node.element,\n element => element.tagName !== 'A');\n return (length - lengthWithoutLinks) / length;\n }\n\nThen, reference your documentation using sphinx-js directives. Our directives work much like Sphinx's standard autodoc ones. You can specify just a function's name... ::\n\n .. js:autofunction:: someFunction\n\n...and a nicely formatted block of documentation will show up in your docs.\n\nYou can also throw in your own explicit parameter list, if you want to note\noptional parameters::\n\n .. js:autofunction:: someFunction(foo, bar[, baz])\n\nParameter properties and destructuring parameters also work fine, using `standard JSDoc syntax <https://jsdoc.app/tags-param.html#parameters-with-properties>`_::\n\n /**\n * Export an image from the given canvas and save it to the disk.\n *\n * @param {Object} options Output options\n * @param {string} options.format The output format (``jpeg``, ``png``, or\n * ``webp``)\n * @param {number} options.quality The output quality when format is\n * ``jpeg`` or ``webp`` (from ``0.00`` to ``1.00``)\n */\n function saveCanvas({ format, quality }) {\n // ...\n }\n\nExtraction of default parameter values works as well. These act as expected, with a few caveats::\n\n /**\n * You must declare the params, even if you have nothing else to say, so\n * JSDoc will extract the default values.\n *\n * @param [num]\n * @param [str]\n * @param [bool]\n * @param [nil]\n */\n function defaultsDocumentedInCode(num=5, str=\"true\", bool=true, nil=null) {}\n\n /**\n * JSDoc guesses types for things like \"42\". If you have a string-typed\n * default value that looks like a number or boolean, you'll need to\n * specify its type explicitly. Conversely, if you have a more complex\n * value like an arrow function, specify a non-string type on it so it\n * isn't interpreted as a string. Finally, if you have a disjoint type like\n * {string|Array} specify string first if you want your default to be\n * interpreted as a string.\n *\n * @param {function} [func=() => 5]\n * @param [str=some string]\n * @param {string} [strNum=42]\n * @param {string|Array} [strBool=true]\n * @param [num=5]\n * @param [nil=null]\n */\n function defaultsDocumentedInDoclet(func, strNum, strBool, num, nil) {}\n\nYou can even add additional content. If you do, it will appear just below any extracted documentation::\n\n .. js:autofunction:: someFunction\n\n Here are some things that will appear...\n\n * Below\n * The\n * Extracted\n * Docs\n\n Enjoy!\n\n``js:autofunction`` has one option, ``:short-name:``, which comes in handy for chained APIs whose implementation details you want to keep out of sight. When you use it on a class method, the containing class won't be mentioned in the docs, the function will appear under its short name in indices, and cross references must use the short name as well (``:func:`someFunction```)::\n\n .. js:autofunction:: someClass#someFunction\n :short-name:\n\n``autofunction`` can also be used on callbacks defined with the `@callback tag <https://jsdoc.app/tags-callback.html>`_.\n\nThere is experimental support for abusing ``autofunction`` to document `@typedef tags <https://jsdoc.app/tags-typedef.html>`_ as well, though the result will be styled as a function, and ``@property`` tags will fall misleadingly under an \"Arguments\" heading. Still, it's better than nothing until we can do it properly.\n\nautoclass\n---------\n\nWe provide a ``js:autoclass`` directive which documents a class with the concatenation of its class comment and its constructor comment. It shares all the features of ``js:autofunction`` and even takes the same ``:short-name:`` flag, which can come in handy for inner classes. The easiest way to use it is to invoke its ``:members:`` option, which automatically documents all your class's public methods and attributes::\n\n .. js:autoclass:: SomeEs6Class(constructor, args, if, you[, wish])\n :members:\n\nYou can add private members by saying... ::\n\n .. js:autoclass:: SomeEs6Class\n :members:\n :private-members:\n\nPrivacy is determined by JSDoc ``@private`` tags or TypeScript's ``private`` keyword.\n\nExclude certain members by name with ``:exclude-members:``::\n\n .. js:autoclass:: SomeEs6Class\n :members:\n :exclude-members: Foo, bar, baz\n\nOr explicitly list the members you want. We will respect your ordering. ::\n\n .. js:autoclass:: SomeEs6Class\n :members: Qux, qum\n\nWhen explicitly listing members, you can include ``*`` to include all unmentioned members. This is useful to have control over ordering of some elements, without having to include an exhaustive list. ::\n\n .. js:autoclass:: SomeEs6Class\n :members: importMethod, *, uncommonlyUsedMethod\n\nFinally, if you want full control, pull your class members in one at a time by embedding ``js:autofunction`` or ``js:autoattribute``::\n\n .. js:autoclass:: SomeEs6Class\n\n .. js:autofunction:: SomeEs6Class#someMethod\n\n Additional content can go here and appears below the in-code comments,\n allowing you to intersperse long prose passages and examples that you\n don't want in your code.\n\nautoattribute\n-------------\n\nThis is useful for documenting public properties::\n\n class Fnode {\n constructor(element) {\n /**\n * The raw DOM element this wrapper describes\n */\n this.element = element;\n }\n }\n\nAnd then, in the docs... ::\n\n .. autoclass:: Fnode\n\n .. autoattribute:: Fnode#element\n\nThis is also the way to document ES6-style getters and setters, as it omits the trailing ``()`` of a function. The assumed practice is the usual JSDoc one: document only one of your getter/setter pair::\n\n class Bing {\n /** The bong of the bing */\n get bong() {\n return this._bong;\n }\n\n set bong(newBong) {\n this._bong = newBong * 2;\n }\n }\n\nAnd then, in the docs... ::\n\n .. autoattribute:: Bing#bong\n\nDodging Ambiguity With Pathnames\n--------------------------------\n\nIf you have same-named objects in different files, use pathnames to disambiguate them. Here's a particularly long example::\n\n .. js:autofunction:: ./some/dir/some/file.SomeClass#someInstanceMethod.staticMethod~innerMember\n\nYou may recognize the separators ``#.~`` from `JSDoc namepaths <https://jsdoc.app/about-namepaths.html>`_; they work the same here.\n\nFor conciseness, you can use any unique suffix, as long as it consists of complete path segments. These would all be equivalent to the above, assuming they are unique within your source tree::\n\n innerMember\n staticMethod~innerMember\n SomeClass#someInstanceMethod.staticMethod~innerMember\n some/file.SomeClass#someInstanceMethod.staticMethod~innerMember\n\nThings to note:\n\n* We use simple file paths rather than JSDoc's ``module:`` prefix or TypeDoc's ``external:`` or ``module:`` ones.\n* We use simple backslash escaping exclusively rather than switching escaping schemes halfway through the path; JSDoc itself `is headed that way as well <https://github.com/jsdoc3/jsdoc/issues/876>`_. The characters that need to be escaped are ``#.~(/``, though you do not need to escape the dots in a leading ``./`` or ``../``. A really horrible path might be... ::\n\n some/path\\ with\\ spaces/file.topLevelObject#instanceMember.staticMember\\(with\\(parens\n* Relative paths are relative to the ``js_source_path`` specified in the config. Absolute paths are not allowed.\n\nBehind the scenes, sphinx-js will change all separators to dots so that...\n\n* Sphinx's \"shortening\" syntax works: ``:func:`~InwardRhs.atMost``` prints as merely ``atMost()``. (For now, you should always use dots rather than other namepath separators: ``#~``.)\n* Sphinx indexes more informatively, saying methods belong to their classes.\n\nSaving Keystrokes By Setting The Primary Domain\n-----------------------------------------------\n\nTo save some keystrokes, you can set ``primary_domain = 'js'`` in conf.py and then say (for example) ``autofunction`` rather than ``js:autofunction``.\n\nTypeScript: Getting Superclass and Interface Links To Work\n----------------------------------------------------------\n\nTo have a class link to its superclasses and implemented interfaces, you'll need to document the superclass (or interface) somewhere using ``js:autoclass`` or ``js:class`` and use the class's full (but dotted) path when you do::\n\n .. js:autoclass:: someFile.SomeClass\n\nUnfortunately, Sphinx's ``~`` syntax doesn't work in these spots, so users will see the full paths in the documentation.\n\nConfiguration Reference\n-----------------------\n\n``js_language``\n Use 'javascript' or 'typescript' depending on the language you use. The default is 'javascript'.\n\n``js_source_path``\n A list of directories to scan (non-recursively) for JS or TS source files, relative to Sphinx's conf.py file. Can be a string instead if there is only one. If there is more than one, ``root_for_relative_js_paths`` must be specified as well. Defaults to '../'.\n\n``jsdoc_config_path``\n A conf.py-relative path to a JSDoc config file, which is useful if you want to specify your own JSDoc options, like recursion and custom filename matching. If using TypeDoc, you can also point to a ``tsconfig.json`` file.\n\n``root_for_relative_js_paths``\n Relative JS entity paths are resolved relative to this path. Defaults to ``js_source_path`` if it is only one item.\n\n``jsdoc_cache``\n Path to a file where JSDoc output will be cached. If omitted, JSDoc will be run every time Sphinx is. If you have a large number of source files, it may help to configure this value. But be careful: the cache is not automatically flushed if your source code changes; you must delete it manually.\n\nExample\n=======\n\nA good example using most of sphinx-js's functionality is the Fathom documentation. A particularly juicy page is https://mozilla.github.io/fathom/ruleset.html. Click the \"View page source\" link to see the raw directives.\n\n`ReadTheDocs <https://readthedocs.org/>`_ is the canonical hosting platform for Sphinx docs and now supports sphinx-js as an opt-in beta. Put this in the ``.readthedocs.yml`` file at the root of your repo::\n\n requirements_file: docs/requirements.txt\n build:\n image: latest\n\nThen put the version of sphinx-js you want in ``docs/requirements.txt``. For example... ::\n\n sphinx-js==3.1.2\n\nOr, if you prefer, the Fathom repo carries a `Travis CI configuration <https://github.com/mozilla/fathom/blob/92304b8ad4768e90c167c3d93f9865771f5a6d80/.travis.yml#L41>`_ and a `deployment script <https://github.com/mozilla/fathom/blob/92304b8ad4768e90c167c3d93f9865771f5a6d80/tooling/travis-deploy-docs>`_ for building docs with sphinx-js and publishing them to GitHub Pages. Feel free to borrow them.\n\nCaveats\n=======\n\n* We don't understand the inline JSDoc constructs like ``{@link foo}``; you have to use Sphinx-style equivalents for now, like ``:js:func:`foo``` (or simply ``:func:`foo``` if you have set ``primary_domain = 'js'`` in conf.py.\n* So far, we understand and convert the JSDoc block tags ``@param``, ``@returns``, ``@throws``, ``@example`` (without the optional ``<caption>``), ``@deprecated``, ``@see``, and their synonyms. Other ones will go *poof* into the ether.\n\nTests\n=====\n\nRun the tests using tox, which will also install JSDoc and TypeDoc at pinned versions::\n\n pip install tox\n tox\n\nVersion History\n===============\n\n3.2.2: (September 20th, 2023)\n * Remove Sphinx upper-bound requirement. (#227)\n * Drop support for Python 3.7. (#228)\n\n Thank you to Will Kahn-Greene!\n\n3.2.1: (December 16th, 2022)\n * Fix xrefs to static functions. (#178)\n * Add support for jsdoc 4.0.0. (#215)\n\n Thank you to xsjad0 and Will Kahn-Greene!\n\n3.2.0: (December 13th, 2022)\n * Add \"static\" in front of static methods.\n * Pin Jinja2 and markupsafe versions. (#190)\n * Track dependencies; do not read all documents. This improves speed of incremental updates. (#194)\n * Support Python 3.10 and 3.11. (#186)\n * Support Sphinx >= 4.1.0. (#209)\n * Fix types warning for ``js_source_path`` configuration item. (#182)\n\n Thank you Stefan 'hr' Berder, David Huggins-Daines, Nick Alexander, mariusschenzle, Erik Rose, lonnen, and Will Kahn-Greene!\n\n3.1.2: (April 15th, 2021)\n * Remove our declared dependency on ``docutils`` to work around the way pip's greedy dependency resolver reacts to the latest version of Sphinx. pip fails when pip-installing sphinx-js because pip sees our \"any version of docutils\" declaration first (which resolves greedily to the latest version, 0.17) but later encounters Sphinx's apparently new ``<0.17`` constraint and gives up. We can revert this when pip's ``--use-feature=2020-resolver`` becomes the default.\n\n3.1.1: (March 23rd, 2021)\n * Rewrite large parts of the suffix tree that powers path lookup. This fixes several crashers.\n\n3.1: (September 10th, 2020)\n * Re-architect language analysis. There is now a well-documented intermediate representation between JSDoc- and TypeDoc-emitted JSON and the renderers. This should make it much faster to merge PRs.\n * Rewrite much of the TypeScript analysis engine so it feeds into the new IR.\n\n * TypeScript analysis used to crash if your codebase contained any overloaded functions. This no longer happens; we now arbitrarily use only the first function signature of each overloaded function.\n * Add support for static properties on TS classes.\n * Support variadic args in TS.\n * Support intersection types (``foo & bar``) in TS.\n * Remove the \"exported from\" module links from classes and interfaces. Functions never had them. Let's see if we miss them.\n * Pathnames for TypeScript objects no longer spuriously use ``~`` after the filename path segment; now they use ``.`` as in JS.\n * More generally, TS pathnames are now just like JS ones. There is no more ``external:`` prefix in front of filenames or ``module:`` in front of namespace names.\n * TS analyzer no longer cares with the current working directory is.\n * Tests now assert only what they care about rather than being brittle to the point of prohibiting any change.\n * No longer show args in the arg list that are utterly uninformative, lacking both description and type info.\n * Class attributes are now listed before methods unless manally ordered with ``:members:``.\n\n3.0.1: (August 10th, 2020)\n * Don't crash when encountering a ``../`` prefix on an object path. This can happen behind the scenes when ``root_for_relative_js_paths`` is set inward of the JS code.\n\n3.0: (July 14th, 2020)\n * Make compatible with Sphinx 3, which requires Python 3.\n * Drop support for Python 2.\n * Make sphinx-js not care what the current working directory is, except for the TypeScript analyzer, which needs further work.\n * Properly RST-escape return types.\n\n2.8: (September 16th, 2019)\n * Display generic TypeScript types properly. Make fields come before methods. (Paul Grau)\n * Combine constructor and class documentation at the top TypeScript classes. (Sebastian Weigand)\n * Switch to pytest as the testrunner. (Sebastian Weigand)\n * Add optional caching of JSDoc output, for large codebases. (Patrick Browne)\n * Fix the display of union types in TypeScript. (Sebastian Weigand)\n * Fix parsing breakage that began in typedoc 0.14.0. (Paul Grau)\n * Fix a data-intake crash with TypeScript. (Cristiano Santos)\n\n2.7.1: (November 16th, 2018)\n * Fix a crash that would happen sometimes with UTF-8 on Windows. #67.\n * Always use conf.py's dir for JSDoc's working dir. #78. (Thomas Khyn)\n\n2.7: (August 2nd, 2018))\n * Add experimental TypeScript support. (Wim Yedema)\n\n2.6: (July 26th, 2018)\n * Add support for ``@deprecated`` and ``@see``. (David Li)\n * Notice and document JS variadic params nicely. (David Li)\n * Add linter to codebase.\n\n2.5: (April 20th, 2018)\n * Use documented ``@params`` to help fill out the formal param list for a\n function. This keeps us from missing params that use destructuring. (flozz)\n * Improve error reporting when JSDoc is missing.\n * Add extracted default values to generated formal param lists. (flozz and erikrose)\n\n2.4: (March 21, 2018)\n * Support the ``@example`` tag. (lidavidm)\n * Work under Windows. Before, we could hardly find any documentation. (flozz)\n * Properly unwrap multiple-line JSDoc tags, even if they have Windows line endings. (Wim Yedema)\n * Drop support for Python 3.3, since Sphinx has also done so.\n * Fix build-time crash when using recommonmark (for Markdown support) under Sphinx >=1.7.1. (jamrizzi)\n\n2.3.1: (January 11th, 2018)\n * Find the ``jsdoc`` command on Windows, where it has a different name. Then\n patch up process communication so it doesn't hang.\n\n2.3: (November 1st, 2017)\n * Add the ability to say \"*\" within the ``autoclass :members:`` option, meaning \"and all the members that I didn't explicitly list\".\n\n2.2: (October 10th, 2017)\n * Add ``autofunction`` support for ``@callback`` tags. (krassowski)\n * Add experimental ``autofunction`` support for ``@typedef`` tags. (krassowski)\n * Add a nice error message for when JSDoc can't find any JS files.\n * Pin six more tightly so ``python_2_unicode_compatible`` is sure to be around.\n\n2.1: (August 30th, 2017)\n * Allow multiple folders in ``js_source_path``. This is useful for gradually migrating large projects, one folder at a time, to JSDoc. Introduce ``root_for_relative_js_paths`` to keep relative paths unambiguous in the face of multiple source paths.\n * Aggregate PathTaken errors, and report them all at once. This means you don't have to run JSDoc repeatedly while cleaning up large projects.\n * Fix a bytes-vs-strings issue that crashed on versions of Python 3 before 3.6. (jhkennedy)\n * Tolerate JS files that have filename extensions other than \".js\". Before, when combined with custom JSDoc configuration that ingested such files, incorrect object pathnames were generated, which led to spurious \"No JSDoc documentation was found for object ...\" errors.\n\n2.0.1: (July 13th, 2017)\n * Fix spurious syntax errors while loading large JSDoc output by writing it to a temp file first. (jhkennedy)\n\n2.0: (May 4th, 2017)\n * Deal with ambiguous object paths. Symbols with identical JSDoc longnames (such as two top-level things called \"foo\" in different files) will no longer have one shadow the other. Introduce an unambiguous path convention for referring to objects. Add a real parser to parse them rather than the dirty tricks we were using before. Backward compatibility breaks a little, because ambiguous references are now a fatal error, rather than quietly referring to the last definition JSDoc happened to encounter.\n * Index everything into a suffix tree so you can use any unique path suffix to refer to an object.\n * Other fallout of having a real parser:\n\n * Stop supporting \"-\" as a namepath separator.\n * No longer spuriously translate escaped separators in namepaths into dots.\n * Otherwise treat paths and escapes properly. For example, we can now handle symbols that contain \"(\".\n * Fix KeyError when trying to gather the constructor params of a plain old\n object labeled as a ``@class``.\n\n1.5.2: (March 22th, 2017)\n * Fix crasher while warning that a specified longname isn't found.\n\n1.5.1: (March 20th, 2017)\n * Sort ``:members:`` alphabetically when an order is not explicitly specified.\n\n1.5: (March 17th, 2017)\n * Add ``:members:`` option to ``autoclass``.\n * Add ``:private-members:`` and ``:exclude-members:`` options to go with it.\n * Significantly refactor to allow directive classes to talk to each other.\n\n1.4: (March 10th, 2017)\n * Add ``jsdoc_config_path`` option.\n\n1.3.1: (March 6th, 2017)\n * Tolerate @args and other info field lines that are wrapped in the source code.\n * Cite the file and line of the source comment in Sphinx-emitted warnings and errors.\n\n1.3: (February 21st, 2017)\n * Add ``autoattribute`` directive.\n\n1.2: (February 14th, 2017)\n * Always do full rebuilds; don't leave pages stale when JS code has changed but the RSTs have not.\n * Make Python-3-compatible.\n * Add basic ``autoclass`` directive.\n\n1.1: (February 13th, 2017)\n * Add ``:short-name:`` option.\n\n1.0: (February 7th, 2017)\n * Initial release, with just ``js:autofunction``\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Support for using Sphinx on JSDoc-documented JS code",
"version": "3.2.2",
"project_urls": {
"Homepage": "https://github.com/mozilla/sphinx-js"
},
"split_keywords": [
"sphinx",
"documentation",
"docs",
"javascript",
"js",
"jsdoc",
"restructured",
"typescript",
"typedoc"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6b57e489ceaef5f1e5284000d274bdc785d7e855ef525c8ce5e382b660de5692",
"md5": "2255ffaaa14a9b7d98507881114b0c88",
"sha256": "05d9e5fe7d3ae745e19fd05a5b477218d81c89ab5ab3134f4a65e3ee7b430420"
},
"downloads": -1,
"filename": "sphinx_js-3.2.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "2255ffaaa14a9b7d98507881114b0c88",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 86375,
"upload_time": "2023-09-20T15:45:48",
"upload_time_iso_8601": "2023-09-20T15:45:48.592170Z",
"url": "https://files.pythonhosted.org/packages/6b/57/e489ceaef5f1e5284000d274bdc785d7e855ef525c8ce5e382b660de5692/sphinx_js-3.2.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "51a20d8bc324e43e85bdb256a716af23348a01bb5e58d0b5540745d52ef2edc9",
"md5": "622db5264cc75944c6d5be5daed4cd5d",
"sha256": "9e3105994dd0aa6d3257b8b4195dca38e335b223bf28dbec8699f1b624b55ad4"
},
"downloads": -1,
"filename": "sphinx-js-3.2.2.tar.gz",
"has_sig": false,
"md5_digest": "622db5264cc75944c6d5be5daed4cd5d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 73009,
"upload_time": "2023-09-20T15:45:50",
"upload_time_iso_8601": "2023-09-20T15:45:50.393923Z",
"url": "https://files.pythonhosted.org/packages/51/a2/0d8bc324e43e85bdb256a716af23348a01bb5e58d0b5540745d52ef2edc9/sphinx-js-3.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-20 15:45:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mozilla",
"github_project": "sphinx-js",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "sphinx-js"
}
JSON
