From 400e01c3d75a66d807381d5d36ebea3855a3d5cc Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Mon, 23 Dec 2024 19:44:43 -0500 Subject: [PATCH] Fix links and code blocks --- README.rst | 60 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 36 insertions(+), 24 deletions(-) diff --git a/README.rst b/README.rst index 62b9639..219060c 100644 --- a/README.rst +++ b/README.rst @@ -10,10 +10,10 @@ 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 `_ +sphinx-js lets you use the industry-leading `Sphinx `__ documentation tool with JS projects. It provides a handful of directives, patterned after the Python-centric `autodoc -`_ ones, for pulling +`__ 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. @@ -73,22 +73,34 @@ Setup 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. +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' + + 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 + The domain is ``js`` even if you're writing TypeScript. Then you can omit all the "js:" prefixes in the directives below. Use @@ -98,7 +110,7 @@ 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 -`_. +`__. For a quick start, just add things to index.rst until you prove things are working. @@ -137,7 +149,7 @@ optional parameters:: Parameter properties and destructuring parameters also work fine, using `standard JSDoc syntax -`_:: +`__:: /** * Export an image from the given canvas and save it to the disk. @@ -208,10 +220,10 @@ references must use the short name as well (``:func:`someFunction```):: :short-name: ``autofunction`` can also be used on callbacks defined with the `@callback tag -`_. +`__. There is experimental support for abusing ``autofunction`` to document -`@typedef tags `_ as well, though the +`@typedef tags `__ 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. @@ -315,7 +327,7 @@ 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 -`_; they work the same here. +`__; 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 @@ -332,7 +344,7 @@ Things to note: ``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 - `_. The characters that need to + `__. 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:: @@ -398,10 +410,10 @@ 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. +``__. Click the "View page +source" link to see the raw directives. -`ReadTheDocs `_ is the canonical hosting platform for +`ReadTheDocs `__ 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:: @@ -415,9 +427,9 @@ example:: sphinx-js==3.1.2 Or, if you prefer, the Fathom repo carries a `Travis CI configuration -`_ +`__ and a `deployment script -`_ +`__ for building docs with sphinx-js and publishing them to GitHub Pages. Feel free to borrow them.