Documentation #36243
Updated by Ernesto Puerta over 5 years ago
h3. Intro
This is review of a bunch of tools suitable for documenting the code. This is aimed at complementing the existing doc sources:
* Ceph docs (doc/mgr/dashboard.rst): user focus
* README: user focus
* HACKING.rst: dev focus (introductory)
* Swagger API docs: dev focus (as long as API is not meant to be consumed externally).
Some missing doc areas would be:
* Architecture docs
* Implementation docs
Both things may be covered with doc generators (Doxygen, Sphinx, etc). Due to the diversity of languages we may find:
* **General purpose doc generators**
** "**Sphinx**":http://www.sphinx-doc.org/en/master/ is extensively used in Ceph docs. There are different plugins for JS support, most based on "JSDoc":http://usejsdoc.org/: "sphinx-js":https://pypi.org/project/sphinx-js/.
* **Language-specific generatos**:
** "**Compodoc**":https://compodoc.app/guides/getting-started.html is an Angular focused tool for auto-doc'ing, also parsing JSDoc tags. ["Screenshots":https://medium.com/learnwithrahul/automated-documentation-for-your-typescript-angular-projects-35746aa0ad5e] ["Online demo":https://compodoc.github.io/compodoc-demo-todomvc-angular/]
** "**TypeDoc**":http://typedoc.org/api/: Typescript specific.