search

rinuboney / clatern

Machine Learning in Clojure
Eclipse Public License 1.0
67 stars 12 forks source link

Research Clojure API doc generation and propose doc strategy for Clatern #10

Closed rnowling closed 9 years ago

rnowling commented 9 years ago

I found 3 libraries for generating docs from docstrings:

Autodoc is used by Clojure and Incanter. Codox is used by Compojure and Ring. Marginalia was started by fogus.

Autodoc and Codox are the more familiar style of API docs while Marginalia takes a literate programming approach. I happen to find the Autodoc and Marginalia output a bit frustrating to navigate and like the layout of the Codox docs more.

Codox supports plain-text or markdown formatting of docstrings. Marginalia supports Latex natively. which could be useful since Clatern is math heavy. Latex support could be added to Codox with some effort.

All three doc systems can be integrated into lein. I found info for pushing Autodoc and Codox to GitHub project pages, which would make hosting the docs very easy. I haven't found instructions for Marginalia after a precursory search.

@rinuboney Any thoughts or preferences?

rinuboney commented 9 years ago

I find Marginalia like literate programming approach visually appealing but hard to navigate. Both Autodoc and Codox looks like potential choices. Latex support would be nice.

Overall, I think I favour Codox.