Documentation process and tools

[hammer]

The Hitchhiker's Guide to Python suggests Sphinx to author documentation and Read the Docs to host it.

There have been some new developments in this domain recently, so let's evaluate our options before selecting a process and tools.

[hammer]

Sphinx appears to use reStructuredText as its markup language and Docutils to parse and generate documents. It appears there is a Markdown parser as well.

I found Who needs pandoc when you have Sphinx? to be a useful description of what Sphinx adds to Docutils.

[hammer]

Another approach is to use MkDocs to author and generate documents and then GitHub pages or Google Cloud to host the docs.

https://github.com/scifabric/docs.pybossa.com is an example of this approach.

https://github.com/squidfunk/mkdocs-material provides a material design theme for mkdocs documentation.

[hammer]

It appears that offline documentation browsers like Zeal, Dash, and DevDocs are popular. I don't use any of these, but if it's not too hard, we should ensure our docs can be imported into those tools.

[hammer]

NumPy

NumPy’s Documentation has information on how NumPy does documentation, including numpydoc, their Sphinx extensions.

Pandas

Contributing to the documentation points to pandas docstring guide. They claim to use the PyData Sphinx Theme, also used by Bokeh and JupyterHub.

The documentation is written in reStructuredText, which is almost like writing in plain English, and built using Sphinx.

They also appear to be in the process of factoring out a Sphinx extension for documenting accessors that is now used by xarray as well: keewis/sphinx-autosummary-accessors.

Dask

Contributing to Documentation:

Dask uses Sphinx for documentation, hosted on https://readthedocs.org. Documentation is maintained in the RestructuredText markup language (.rst files)

Has its own Sphinx theme.

It extends the sphinx_rtd_theme project, but adds custom styling and a navigation bar to additional Dask subprojects.

Xarray

Contributing to the documentation calls out the IPython Directive for putting code into docs.

The documentation is written in reStructuredText, which is almost like writing in plain English, and built using Sphinx

Built with Sphinx using a theme provided by Read the Docs

Zarr

Documentation notes that all examples should pass as doctests.

Zarr uses Sphinx for documentation, hosted on readthedocs.org. Documentation is written in the RestructuredText markup language (.rst files)

Built with Sphinx using a theme provided by Read the Docs

[hammer]

Some other options

• Docusaurus from Facebook seems to have a lot of flexibility for generating nice documentation sites. I'm not sure we have enough frontend development skills to make this tool a reasonable choice.
• GitBook (disclosure: I'm an investor) is another option if we want to make a fancy site.

[jeromekelleher]

Sphinx is great, I think we'd want some compelling motivation to use anything else tbh. I don't have any real opinions in terms of themes and hosting.

If it's at all feasible, I'd suggest using Markdown rather than RST though. Markdown is just so much more intuitive, and many more people know it. It's a real barrier to contributors asking them to learn RST when doing docs. But I haven't investigated how good Markdown support in sphinx is, so it might be a non-starter.

[hammer]

Hail recently added documentation search using Algolia's DocSearch.

RTD appears to have done some work on an In Doc Search UI, and there's a Sphinx extension for it, but I'm not sure that I've seen it in the wild.

[hammer]

I'd suggest using Markdown rather than RST

While that was my strong bias headed into this survey, I was surprised to find that most PyData ecosystem projects still use reStructuredText, so I think it may be worth asking some developers on those more mature projects why they haven't switched.

[hammer]

I suppose https://github.com/pystatgen/sgkit/pull/9 is related to this discussion.

[jeromekelleher]

I think it may be worth asking some developers on those more mature projects why they haven't switched.

I'd bet on one word: inertia. It's a whole pile of work to switch - I know that's why I haven't done it.

[alimanfoo]

FWIW I do prefer markdown over rst and did recently look at support for markdown in sphinx. Bottom line I think you can use markdown, but it wasn't obvious how to use many of the sphinx features within it, like all the sphinx directives. There's a relevant SO post here.

[hammer]

Ah we were looking separately at MyST as a format for Jupyter notebook code reviews with mystify and MyST-NB. That may be our best bet to get Markdown syntax and Sphinx directives.

Unfortunately, it's a bit bleeding edge:

The MyST parser is in a beta stage, and may change rapidly in its implementation and machinery.

On the other hand, the MyST-Markdown VS Code extension has 135 installs, so there is a reasonable user community.

Looking into MyST a bit further, it appears to be primarily developed by two people, @choldgraf at Berkeley and @chrisjsewell at Imperial. If we decide to go forward with MyST, it might be a good idea to check in with them to be sure they plan to keep working on it for a while.

[alimanfoo]

MyST looks good.

Btw for jupyter notebook code reviews we use reviewnb.

[hammer]

for jupyter notebook code reviews we use reviewnb.

We've hit some deficiencies with this product, unfortunately, so are searching for alternatives at the moment.

[alimanfoo]

for jupyter notebook code reviews we use reviewnb.

We've hit some deficiencies with this product, unfortunately, so are searching for alternatives at the moment.

Ah OK, would be interested to know what you missed and what alternatives you find. Pretty key tool in our analysis work, has been fine so far but have missed the ability to make line comments.

[tomwhite]

I'd rather go with something that is proven to work well, even if it's a bit harder to get up to speed on (RST + Sphinx) than newer things that have gaps in areas we don't know if we need yet.

[hammer]

@tomwhite as noted by Aaron Meurer on Twitter, once nice thing about MyST is that we don't need to commit entirely to it:

With myst you can write markdown in .md files and still use restructured text in .rst files. And cross references work between them

I also did not realize that MyST was only publicly announced on June 15! The comments on that tweet are useful. In particular, one user notes that MyST does not yet work for docstrings, and points to the napoleon docstring preprocessor and autodoc. executablebooks/MyST-Parser#164 has been filed to close the docstring loophole for MyST.

It's also interesting to look at issues and PRs from projects that have moved to MyST already, e.g. poliastro/poliastro#977 and asmeurer/brown-water-python#2.

While I'm generally in the "use boring technologies" camp, especially for things like documentation, I am also in the "don't make me learn another domain-specific language" camp, and would love to be able to write Markdown.

Does it make sense to try to use MyST in one place first, perhaps in one of our IO repos?

[tomwhite]

Does it make sense to try to use MyST in one place first, perhaps in one of our IO repos?

I was hoping we could avoid having separate documentation for each repo, and just have a single set of docs in one repo, so we can avoid the problem of knitting it all together. The IO docs will be fairly small, so putting them in the main repo shouldn't be too much of a stretch.

[hammer]

The IO docs will be fairly small, so putting them in the main repo shouldn't be too much of a stretch.

Fair enough. Regardless of the location of the .md file, though, how would you feel about trying MyST for the documentation of a part of sgkit?

[hammer]

After some discussion on the 20200709 developer call, we've decided to write docs in ReST, not MyST, for now.

We still have some decisions to make

• What docstring style will we adopt?
• What Sphinx extensions will we use?
• Where will we host the docs?

I'll do a bit more research and write up my findings for discussion next week.

[hammer]

Also be sure to run doctest in our CI.

[hammer]

@jeromekelleher notes there are linters for docstrings too.

[jeromekelleher]

Some good links here:

https://pypi.org/project/flake8-rst-docstrings/

https://github.com/asottile/blacken-docs

[hammer]

https://github.com/jdillard/continuous-sphinx has some code for deploying Sphinx docs to Netlify, though they use Travis CI in place of GH Actions.

[hammer]

I think we can close this issue with #51 going in. Let me know if y'all think otherwise.