diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index c4cb0fd..e469439 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -55,6 +55,8 @@ Comments Comments are written directly inside the code, either using the hash sign (#) or a docstring_. +.. _docstring: docstrings_ + Finding the correct balance between undocumented code and verbose and useless comment boilerplates is difficult, and is the subject of heated discussion among developers. @@ -193,6 +195,10 @@ Multi-line docstrings: :: if imag == 0.0 and real == 0.0: return complex_zero ... + +.. _sphinx-ref: + + Sphinx ------ @@ -220,8 +226,16 @@ should help you familiarize yourself with its syntax. Other Tools ::::::::::: -that old thing --------------- + +Epydoc +------ +`Epydoc `_ generates API documentation based on docstrings. +Epydoc is able to parse docstrings marked up with :ref:`reStructuredText-ref`, +`Javadoc `_, +`epytext `_ or plaintext. +It supports various output formats, most notable HTML, PDF or LaTeX documents. + +The development of Epydoc is discontinued. You should use :ref:`sphinx-ref` instead. pycco / docco / shocco ----------------------