Docs: RTD vs MkDocs

[dgasmith]

I recently moved one of my repo's over to MkDocs. I found it quite the enjoyable experience and thought I would share. Example

RTD/Sphinx:

• Pros:
  • Standard in the ecosystem, but declining in popularity
  • Large suite of functionality like autodoc
  • RTD provides a fairly nice hosted solution for free (with ads)
• Cons:
  • RST is fairly painful and a bit too "magic"
  • Sphinx ecosystem is a bit archaic and hard to navigate
  • Produced pages do not feel modern or engaging.

MkDocs/GitHub hosting:

• Pros:
  • All markdown, pretty standard to edit
  • Very simple deploys.
  • Material UI-based theme feels quite modern (we based Envision off it as well).
  • Batteries included is fairly robust.
• Cons:
  • Add-on/extension ecosystem is young (audoc in particular) requires a bit more manual work.
  • Much more "plain" javascript with a concrete idea of partials from JAMstack making it much more easily extensible.
• Neutral:
  • Config is in YML like everything else from k8s to conda.

The pros/cons does convolve the host/static site generator into a single list and Sphinx+GH hosting is perfectly possible. GitHub seems to be encouraging a all-in-one solution (actions, projects, wikis, website hosting, and I'm sure more to come) which leans a lot on a single solution. I find the the cognitive overhead associated with sticking with standard GHA/Markdown quite nice and much less "let me trawl through sphinx/RTD docs for a glimmer of hope" kinds of operations.

PS: I'm a pretty big fan of netlify for general JAMStack depending on the sophistication required.

[loriab]

The MkDocs docs do look nice. My biggest reservation is that I haven't seen a system like intersphinx to link to other projects' documentation. As autodoc with signature typehints roll out, intersphinx becomes less optional.

I second netlify and GH hosting over RTD. I recently had to rule out RTD because I needed to add an extra command to sphinx make html. GH hosting worked nicely in this case.

    - name: Build Documentation
      run: |
        python -m pip install . --no-deps
        cd docs
        make html

    - name: GitHub Pages Deploy
      uses: JamesIves/github-pages-deploy-action@4.1.1
      with:
        branch: gh-pages
        folder: docs/build/html

[j-wags]

Just to chime in on our infrastructure: The OpenFF toolkit is still on RTD. No bad experiences to speak of. We're using MyST so I've mostly escaped the tyranny of rST. (cc @Yoshanuikabundi who facilitated the transition)

Our PRs now have docs-building tests, and we updated our developers instructions so building docs locally is less painful.

If we start having trouble I'll probably try move over to GHA, just to keep more of our automation under one roof.

[jaimergp]

I tried MkDocs for KinoML and ended up switching back to Sphinx just because of the API docstrings autogeneration. The Material for Sphinx theme port is okayish too.

[SimonBoothroyd]

The MkDocs docs do look nice. My biggest reservation is that I haven't seen a system like intersphinx to link to other projects' documentation. As autodoc with signature typehints roll out, intersphinx becomes less optional.

+1 - this has been one of the big sticking points for me as well.

mkdocstrings does seem to be maturing nicely, offering more support for things like pydantic natively (although I do really like autodoc_pydantic) and numpy style docstrings which are commonly used across the OpenFF stack.

But I think until mkdocstrings/pytkdocs#13 and mkdocstrings/mkdocstrings#115 are resolved I'd be hesitant to swap.