Documentation #36243

Updated by Ernesto Puerta over 2 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**": is extensively used in Ceph docs. There are different plugins Sphinx has support for JS support, most based on "JSDoc": "sphinx-js": by means of external libraries (not specifically TS or Angular): "sphinx-js":
* **Language-specific generatos**:
** "**Compodoc**": is an Angular focused tool for auto-doc'ing, also parsing JSDoc tags.
** "**TypeDoc**": Typescript specific.