PyBitmessage-2024-12-05/docs/contribute.dir/develop.dir/documentation.rst

Documentation
=============

Sphinx is used to pull richly formatted comments out of code, merge them with hand-written documentation and render it
in HTML and other formats.

To build the docs, simply run `$ fab -H localhost build_docs` once you have set up Fabric.

Restructured Text (RsT) vs MarkDown (md)
----------------------------------------

There's much on the internet about this. Suffice to say RsT_ is preferred for Python documentation while md is preferred for web markup or for certain other languages.

.. _Rst: [http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html]` style is preferred, 

`md` files can also be incorporated by using mdinclude directives in the indices. They are translated to RsT before rendering to the various formats. Headers are translated as a hard-coded level `(H1: =, H2: -, H3: ^, H4: ~, H5: ", H6: #`.  This represents a small consideration for both styles. If markup is not translated to rst well enough, switch to rst.
Added: Sphinx docs, testing readthedocs integration * Added: Sphinx configuration including readthedocs config * Added: Sphinx fabric task to auto-document the project * Fixed: Some issues in the code causing autodoc to fail when parsing * Added: Manual docs - structure, proof of concepts and RsT examples * Fixed: RsT formatting in docstrings * Fixed: Some adjacent minor style and lint issues 2018-05-26 14:43:21 +02:00			`Documentation`
			`=============`

			`Sphinx is used to pull richly formatted comments out of code, merge them with hand-written documentation and render it`
			`in HTML and other formats.`

			To build the docs, simply run `$ fab -H localhost build_docs` once you have set up Fabric.

			`Restructured Text (RsT) vs MarkDown (md)`
			`----------------------------------------`

			`There's much on the internet about this. Suffice to say RsT_ is preferred for Python documentation while md is preferred for web markup or for certain other languages.`

			.. _Rst: [http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html]` style is preferred,

			`md` files can also be incorporated by using mdinclude directives in the indices. They are translated to RsT before rendering to the various formats. Headers are translated as a hard-coded level `(H1: =, H2: -, H3: ^, H4: ~, H5: ", H6: #`. This represents a small consideration for both styles. If markup is not translated to rst well enough, switch to rst.