DAGWorks-Inc / hamilton

Hamilton helps data scientists and engineers define testable, modular, self-documenting dataflows, that encode lineage/tracing and metadata. Runs and scales everywhere python does.
https://hamilton.dagworks.io/en/latest/
BSD 3-Clause Clear License
1.78k stars 113 forks source link

Switch from sphinx to MkDocs #1170

Open jernejfrank opened 8 hours ago

jernejfrank commented 8 hours ago

Is your feature request related to a problem? Please describe. Documenting code in RST is tedious, setting up sphinx is another hurdle to overcome for contributions and you need to re-render it every time you want to see changes.

Describe the solution you'd like Switching to MkDocs: https://www.mkdocs.org/user-guide/writing-your-docs/

For one-sided comparison to Sphinx: https://dev.to/coderatul/simplify-your-documentation-workflow-with-mkdocs-a-markdown-based-alternative-to-sphinx-365j#:~:text=Sphinx%20and%20MkDocs%20are%20two,easier%20to%20use%20than%20Sphinx.

Describe alternatives you've considered Leave it as is.

I am fully prepared for this to be shut down, but still worth a try.

elijahbenizzy commented 7 hours ago

Context:

  1. @jernejfrank and I were complainng about RST, it's absolute junk
  2. LOL, we switched over two years ago IIRC
  3. Intermediate world is [(https://www.sphinx-doc.org/en/master/usage/markdown.html) lets us write in markdown...