## Tools - [[Sphinx]] ## Read The Docs ### Public Documentation <https://www.readthedocs.org> can link to publix github projects and when you successfully commit into a branch it will rebuild your docs on the readthedocs site. ### Private Docs In [[Azure#Pipelines]] i can build the docs and return an artifact and deploy that artifact somewhere afterwards ## Syntax ### Block Content #### Code Block 2 colons after a paragraph and indent next section then that becomes a code Block ```rst this is an ordinary paragraph:: def say_hi(): print('Hello world') And back to regular text ``` Using double colons default renders code as python so you can be more explicit with ```rst this is an ordinary paragraph .. code-block: python def say_hi(): print('Hello world') And back to regular text ``` the `.. code-block: python` is something called a directive #### Doctest Blocks > Doctest blocks (ref) are interactive Python sessions cut-and-pasted into docstrings. They do not require the literal blocks syntax. The doctest block must end with a blank line and should not end with an unused prompt: ```rst >>> 1 + 1 2 ``` #### Line Block ```rst | These lines are | broken exactly like in | the source file. ``` #### Lists ##### Unordered List ```rst * first * second * third ``` ##### Ordered List ```rst 1. first 2. second 3. third ``` ##### Dynamic Ordered List ```rst # first # second # nested lists # must be separated from parent list # by blank lines # third ``` #### quote ```rst normal paragraph text indented text is a quote normal paragraph again ``` #### Tables ##### Normal Tables https://docutils.sourceforge.io/docs/ref/rst/directives.html#table ```rst .. table:: Truth table for "not" :widths: auto ===== ===== A not A ===== ===== False True True False ===== ===== ``` ##### CSV Tables https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table-1 ```rst .. csv-table:: Frozen Delights! :header: "Treat", "Quantity", "Description" :widths: 15, 10, 30 "Albatross", 2.99, "On a stick!" "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be crunchy, now would it?" "Gannet Ripple", 1.99, "On a stick!" ``` ##### List Tables https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table ```rst .. list-table:: Frozen Delights! :widths: 15 10 30 :header-rows: 1 * - Treat - Quantity - Description * - Albatross - 2.99 - On a stick! * - Crunchy Frog - 1.49 - If we took the bones out, it wouldn't be crunchy, now would it? * - Gannet Ripple - 1.99 - On a stick! ``` ### Directives directives are like in [[#Code Block]] where you explicitly say to use python `.. code-block:python` ```rst .. image:: mylogo.png ``` #### Substitution Definition ```rst .. |symbol here| image:: symbol.png ``` #### Admonitions <https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions> - Admonitions - `attention` - `caution` - `danger` - `error` - `hint` - `important` - `note` - `tip` - `warning` - and the generic `admonition.` Most themes style only `note` and `warning` specially. ##### custom You can style and define your own custom boxes like `warning` or `note` by using the syntax ```rst .. admonition:: custom-name-here Text here ``` #### Container <https://docutils.sourceforge.io/docs/ref/rst/directives.html#container> ```rst .. container:: custom This paragraph might be rendered in a custom way. ``` Parsing the above results in the following pseudo-XML: ```rst <container classes="custom"> <paragraph> This paragraph might be rendered in a custom way. ``` #### Raw HTML ```rst .. raw:: html <center><iframe width="560" height="315" src="https://www.youtube.com/embed/JQ8RQru-Y9Y" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe></center> ``` Embedd raw HTML in the end product documentation ### Inline Markup Be aware of some restrictions of this markup: it may not be nested, content may not start or end with whitespace: `* text*` is wrong, it must be separated from surrounding text by non-word characters. Use a backslash escaped space to work around that: `thisis\ *one*\ word`. #### Bold ```rst **bold** ``` #### Citations ```rst .. [CIT2002] Just like a footnote, except the label is textual. ``` #### Inline code ```rst ``inline code`` ``` #### Definition Lists ```rst term 1 Definition 1. term 2 Definition 2, paragraph 1. Definition 2, paragraph 2. term 3 : classifier Definition 3. term 4 : classifier one : classifier two Definition 4. \-term 5 Without escaping, this would be an option list item. ``` #### Footnotes ```rst .. [1] A footnote contains body elements, consistently indented by at least 3 spaces. ``` #### Hyperlinks ##### Inline Links `` `Link text <https://domain.invalid/>`_ ``aa ##### Separate Link Text and Definition ```rst This is a paragraph that contains `a link`_. .. _a link: https://domain.invalid/ ``` ##### Hyperlink Targets ```rst .. _Python: https://www.python.org .. _example: The "_example" target above points to this paragraph. ``` #### Italic ```rst *Italic* ``` ### Comments ```rst .. Comments begin with two dots and a space. Anything may follow, except for the syntax of footnotes/citations, hyperlink targets, directives, or substitution definitions. ``` ```rst .. This is a comment. ``` ```rst .. This whole indented block is a comment. Still in the comment. ``` ### Fields Lists ```rst :Date: 2001-08-16 :Version: 1 :Authors: - Me - Myself - I :Indentation: Since the field marker may be quite long, the second and subsequent lines of the field body do not have to line up with the first line, but they must be indented relative to the field name marker, and they must line up with each other. :Parameter i: integer ``` #### Bibliographic Fields The registered bibliographic field names and their corresponding doctree elements are as follows: | Field name | doctree element | |--------------|-----------------| | Abstract | topic | | Address | address | | Author | author | | Authors | authors | | Contact | contact | | Copyright | copyright | | Date | date | | Dedication | topic | | Organization | organization | | Revision | revision | | Status | status | | Version | version | ### Figures https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure ```rst .. figure:: picture.png :scale: 50 % :alt: map to buried treasure This is the caption of the figure (a simple paragraph). The legend consists of all elements after the caption. In this case, the legend consists of this paragraph and the following table: +-----------------------+-----------------------+ | Symbol | Meaning | +=======================+=======================+ | .. image:: tent.png | Campground | +-----------------------+-----------------------+ | .. image:: waves.png | Lake | +-----------------------+-----------------------+ | .. image:: peak.png | Mountain | +-----------------------+-----------------------+ ``` ### Headers ```rst ======== Header 1 ======== -------- Header 2 -------- Header 3 ^^^^^^^^ ``` But also ```rst Also Header 1 ============= Header 2 ******** Header 3 -------- ``` | Markup | Meaning | |--------|-----------------------------| | `#` | with overline, for parts | | `*` | with overline, for chapters | | `=` | for sections | | `-` | for subsections | | `^` | for subsubsections | | `"` | for paragraphs | ### Info Fields In python docstrings these might present as items in the docstrings ```rst :param str name: optional name ``` - info is that it is a `parameter` - follow by type `str` - then the name of the param `name` - and finally the description This can also be borken out onto 2 different lines for legibility sake ```rst :param name: optional name :type name: str ``` ```rst :returns: 'Hello world!' or 'Hello, {name}!' :rtype: str ``` ![[2022-02-17-12-40-09.png]] `:attr block_size:` being used to document a class attribute `:raises ValueError:` To define the exception it may raise and why it will raise that exception ![[2022-02-17-12-41-35.png]] `:meth:` for defining methods