Consider a different documentation generation engine

[aaraney]

Sphinx is okay and is fully featured, however, I am not fond of to the rst format nor the way sphinx generates documentation. I would like a solution that is closer to the tool-chain that we and many other data science minded individuals use (e.g. markdown).

The solution choice should (IMO) be driven by approachability. Meaning:

• it should be easy for someone to read and contribute to our documentation without knowing a markup specification. I would argue that markdown is much more intuitive that rst and thus approachable.
• documentation issues and errors should have a low barrier for a user to report them.
• approachability should also be taken to mean searchable and scanable (scrolling should be limited or at least a choice).
• Our common interfaces should be easy to find and digest.
• A version change log should be accessible.
• The developer documentation experience should be straight forward and require little thought.
• It should be something we want to use when we need to reference our work.

[jarq6c]

Apparently sphinx can use Markdown: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html#using-markdown-with-sphinx

[jarq6c]

I'd like to submit pdoc for consideration: https://pypi.org/project/pdoc/

I generated the attached documentation for hydrotools.metrics by adding __docformat__ = "numpy" to the top of hydrotools.metrics.metrics.py and running pdoc hydrotools.metrics -o htmldocs from the command line.

ht_metrics_docs_example.tar.gz

[jarq6c]

Note pdoc supports embedding Markdown directly in docstrings (the default) and equation rendering.

[jarq6c]

Here's an updated example with rendered math (pdoc hydrotools.metrics -o htmldocs --math). This required no changes to the module itself.

ht_metrics_math.tar.gz

[aaraney]

Given that this has gone stale and I have no plans to look into this in the near future, im going to close this.