Features¶
🔍 Features
ID |
Title |
SI |
Errors |
|---|---|---|---|
Attention Admonition |
no |
||
Caution Admonition |
no |
||
Danger Admonition |
no |
||
Error Admonition |
no |
||
Generic Admonition |
no |
||
Hint Admonition |
no |
||
Important Admonition |
no |
||
Note Admonition |
no |
||
Tip Admonition |
no |
||
Warning Admonition |
no |
||
Built-in HTML Search |
|||
Static File Support |
|||
HTML Theming Support |
|||
Block Quotes |
no |
||
Line Blocks |
no |
||
Code Block Directive |
no |
||
Contents Directive (Local ToC) |
no |
||
CSV Table Directive |
yes |
||
Figure Directive |
yes |
||
Image Directive |
yes |
||
Include Directive |
yes |
||
List Table Directive |
yes |
||
Literal Include Directive |
yes |
||
Math Directive |
no |
||
Raw Content Directive |
no |
||
Rubric Directive |
no |
||
Table Directive with Title |
yes |
||
Table of Contents Tree Directive (toctree) |
yes |
||
Italicized (Emphasis) Text |
no |
||
Escaped Markup Characters |
no |
||
Inline Internal Target |
no |
||
Inline Literal (Code) Text |
no |
||
Named Hyperlink Reference |
yes |
||
Bold (Strong) Text |
no |
||
Citations |
no |
||
Explicit Target Creation |
no |
||
External Hyperlinks |
no |
||
Footnotes |
no |
||
Implicit Hyperlinks from URLs |
no |
||
Internal Cross-References to Labels |
no |
||
Auto-Numbered Lists |
no |
||
Bulleted Lists |
no |
||
Definition Lists |
no |
||
Numbered (Enumerated) Lists |
no |
||
Nested Lists |
no |
||
Option Lists |
no |
||
Directory HTML Output |
yes |
||
ePub 3 Output |
yes |
||
Gettext Message Catalog Output |
|||
HTML Output |
yes |
||
JSON Output |
|||
LaTeX Output |
yes |
||
Man Page Output |
|||
Single-File HTML Output |
yes |
||
Plain Text Output |
|||
Read-in documents with Sphinx |
yes |
ER_FILES_IGNORED; ER_SPH_WRONG_ENCODING; ER_SPH_WRONG_ACCESS |
|
Code Role |
no |
||
Document Role |
no |
||
Emphasis Role |
no |
||
Literal Role |
no |
||
Inline Math Role |
no |
||
Numbered Reference Role |
no |
||
Reference Role |
no |
||
Strong Role |
no |
||
Subscript Role |
no |
||
Superscript Role |
no |
||
Document Title and Subtitle |
no |
||
Section Titles with Underlines |
no |
||
Transitions (Horizontal Lines) |
no |
||
Grid Tables |
yes |
||
Simple Tables |
yes |
Readin all needed rst/md files for the Sphinx project.
|
Inline Text Formatting¶
Use emphasis to italicize text in your documentation. This is *italicized* text.
|
Use strong emphasis to make text bold. This is **bold** text.
|
Use inline literals to display code or commands inline. This is ``inline code``.
|
Create a named hyperlink reference to link to external or internal resources. `Sphinx Documentation <https://www.sphinx-doc.org/en/master/>`__
|
Use internal targets to create cross-references within your documentation. See :ref:`example-section` for more details.
|
Escape special characters to display them as plain text. Use \\* to display an asterisk (*).
|
Use the subscript role to display text as a subscript. H\ :sub:`2`\ O
|
Use the superscript role to display text as a superscript. E = mc\ :sup:`2`
|
Use the strong role to emphasize text strongly. :strong:`Important!`
|
Use the emphasis role to italicize text. :emphasis:`This is emphasized text.`
|
Use the literal role to display inline code or commands. :literal:`print("Hello, World!")`
|
Use the code role to highlight inline code snippets. :code:`def example(): pass`
|
Use the math role to display inline mathematical expressions. :math:`E = mc^2`
|
Structural Elements¶
Use underlines to define section titles in your documentation. Section Title
=============
|
Define a document title and optional subtitle using underlines. Document Title
==============
Subtitle
--------
|
Use transitions to separate sections visually with horizontal lines. --------
|
Use the toctree directive to create a table of contents for your documentation. .. toctree::
:maxdepth: 2
introduction
usage
contribute
|
Use the rubric directive to add a styled heading to your documentation. .. rubric:: Important Notes
|
Lists and Quotes¶
Use bulleted lists to organize items without a specific order. - Item 1
- Item 2
- Item 3
|
Use numbered lists to organize items in a specific order. 1. First item
2. Second item
3. Third item
|
Use auto-numbered lists to let Sphinx automatically number the items. #. First item
#. Second item
#. Third item
|
Use nested lists to create hierarchical structures. - Parent item
- Child item
- Sub-child item
|
Use definition lists to define terms and their descriptions. Term 1
Definition of term 1.
Term 2
Definition of term 2.
|
Use option lists to document command-line options or similar items. -a Enable all features.
-h Display help information.
|
Use block quotes to highlight quoted text or important notes. > This is a block quote.
|
Use line blocks to preserve line breaks in text. | Line 1
| Line 2
| Line 3
|
Directives for Content¶
Use the image directive to include images in your documentation. .. image:: example.png
:alt: Example image
:width: 300px
|
Use the figure directive to include images with captions. .. figure:: example.png
:alt: Example image
This is a caption for the figure.
|
Use the table directive to create tables with titles. .. table:: Example Table
======== ========
Header 1 Header 2
======== ========
Row 1 Data 1
Row 2 Data 2
======== ========
|
Use simple tables for basic tabular data. ======== ========
Header 1 Header 2
======== ========
Row 1 Data 1
Row 2 Data 2
======== ========
|
Use grid tables for more complex table layouts. +----------+----------+
| Header 1 | Header 2 |
+==========+==========+
| Row 1 | Data 1 |
+----------+----------+
| Row 2 | Data 2 |
+----------+----------+
|
Use the CSV table directive to create tables from CSV files. .. csv-table:: Example CSV Table
:file: example.csv
:header-rows: 1
|
Use the list table directive to create tables from lists. .. list-table:: Example List Table
:header-rows: 1
* - Header 1
- Header 2
* - Row 1
- Data 1
* - Row 2
- Data 2
|
Use the code block directive to include syntax-highlighted code snippets. def example():
print("Hello, World!")
|
Use the literal include directive to include external code files. .. literalinclude:: example.py
:language: python
|
Use the math directive to include mathematical equations. .. math::
E = mc^2
|
Use the contents directive to create a local table of contents. .. contents::
:local:
|
Use the include directive to include content from other files. .. include:: other_file.rst
|
Directives for Admonitions¶
Use the note admonition to highlight additional information. .. note::
This is a note.
|
Use the warning admonition to emphasize potential issues or risks. .. warning::
This is a warning.
|
Use the hint admonition to provide helpful tips or suggestions. .. hint::
This is a hint.
|
Use the tip admonition to share useful advice. .. tip::
This is a tip.
|
Use the important admonition to highlight critical information. .. important::
This is important.
|
Use the attention admonition to draw focus to specific content. .. attention::
Pay attention to this.
|
Use the caution admonition to warn about potential problems. .. caution::
Proceed with caution.
|
Use the error admonition to indicate errors or critical issues. .. error::
This is an error.
|
Use the danger admonition to highlight severe risks. .. danger::
This is dangerous.
|
Use the generic admonition to create custom-styled notes. .. admonition:: Custom Title
This is a custom admonition.
|
Hyperlinks and Cross-Referencing¶
Use external hyperlinks to link to external resources. `Sphinx Documentation <https://www.sphinx-doc.org/en/master/>`__
|
Use implicit hyperlinks to automatically create links from URLs. https://www.sphinx-doc.org/en/master/
|
Use internal cross-references to link to labeled sections. See :ref:`example-section` for more details.
|
Use explicit targets to create reusable links. .. _example-target:
This is the target.
See :ref:`example-target`.
|
Use the reference role to create cross-references. :ref:`example-section`
|
Use the document role to link to other documents. :doc:`usage`
|
Use the numbered reference role to create numbered cross-references. :numref:`example-figure`
|
Use footnotes to provide additional information or references. This is a sentence with a footnote. [#]_
.. [#] This is the footnote text.
|
Use citations to reference external sources. This is a citation. [CITATION]_
.. [CITATION] Author, Title, Year.
|
Output and Build System¶
Generate HTML output for your documentation. sphinx-build -b html source/ build/html/
|
Generate a single HTML file for your documentation. sphinx-build -b singlehtml source/ build/singlehtml/
|
Generate HTML output with a directory structure. sphinx-build -b dirhtml source/ build/dirhtml/
|
Generate LaTeX output for your documentation. sphinx-build -b latex source/ build/latex/
|
Generate ePub output for your documentation. sphinx-build -b epub source/ build/epub/
|
Generate man page output for your documentation. sphinx-build -b man source/ build/man/
|
Generate plain text output for your documentation. sphinx-build -b text source/ build/text/
|
Generate JSON output for your documentation. sphinx-build -b json source/ build/json/
|
Generate gettext message catalogs for translations. sphinx-build -b gettext source/ build/gettext/
|
Enable built-in search functionality for HTML output. .. search::
|
Customize the appearance of HTML output using themes. html_theme = 'alabaster'
|
Include static files like images, CSS, or JavaScript in your build. html_static_path = ['_static']
|