restructured-headers-.rst

0.   ReStructuredText headers

ReST headers syntax conventions (... is more what you'd call guidelines than actual rules).

• 0.   ReStructuredText headers
  • 0.1.   Characters to use
  • 0.2.   Automatic Section Numbering
• 1.   Example
  • 1.1.   Chapter 1
  • 1.2.   Chapter 2

---

0.1.   Characters to use

Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, it is better to stick to the same convention throughout a project. For instance:

#	for parts (overlined)
*	for chapters (overlined)
=	for sections
-	for subsections
^	for subsubsections
"	for paragraphs

0.2.   Automatic Section Numbering

The "sectnum" (or "section-numbering") directive automatically numbers sections and subsections in a document (if not disabled by the --no-section-numbering command line option or the sectnum_xform configuration setting) (documentation).

1.   Example

1.1.   Chapter 1

1.1.1.   Section 1

1.1.1.1.   Subsection 1

1.1.1.1.1.   Subsubsection

1.1.1.1.1.1.   Paragraph

(this level is too much for github, i suppose)

Let’s Encrypt performs domain validation by requesting a well-known URL from a domain. If it receives a certain response (the “challenge”), the domain is considered validated. This is similar to how Google Search Console establishes ownership of a website. The response data is provided by certbot, so we need a way for the nginx container to serve files from certbot.

1.2.   Chapter 2

1.2.1.   Section 1

First of all, we need two shared Docker volumes. One for the validation challenges, the other for the actual certificates.

Source:

########
Example
########

**********
Chapter 1
**********

Section 1
==========

Subsection 1
-------------

Subsubsection
^^^^^^^^^^^^^^

Paragraph
""""""""""""

Let’s Encrypt performs domain validation by requesting a well-known URL from a domain. If it receives a certain response (the “challenge”), the domain is considered validated. This is similar to how Google Search Console establishes ownership of a website. The response data is provided by certbot, so we need a way for the nginx container to serve files from certbot.

First of all, we need two shared Docker volumes. One for the validation challenges, the other for the actual certificates.

---

Author:	Alexandr Shavykin
Contact:	[email protected]
Date:	26-Apr-25 02:53:43 PDT

restructured-headers-example.rst

Using Sphinx

reStructuredText

Roles

Sphinx uses interpreted text roles to insert semantic markup into documents. They are written as :rolename:`content`.

The default role (content) has no special meaning by default. You are free to use it for anything you like, e.g. variable names; use the default_role config value to set it to a known role – the any role to find anything or the py:obj role to find Python objects are very useful for this.

Cross-referencing syntax

Cross-references are generated by many semantic interpreted text roles. Basically, you only need to write :role:`target`, and a link will be created to the item named target of the type indicated by role. The link’s text will be the same as target.

Cross-referencing ojbects:

These roles are described with their respective domains:

• Python
• C
• C++
• JavaScript
• ReST

restructured-headers-example.rst.raw

##############################
Using Sphinx
##############################

*****************
reStructuredText
*****************

Roles
=====

Sphinx uses interpreted text roles to insert semantic markup into documents. They are written as ``:rolename:`content```.

The default role (``content``) has no special meaning by default. You are free to use it for anything you like, e.g. variable names; use the default_role config value to set it to a known role – the ``any`` role to find anything or the ``py:obj`` role to find Python objects are very useful for this.

Cross-referencing syntax
---------------------------

Cross-references are generated by many semantic interpreted text roles. Basically, you only need to write ``:role:`target```, and a link will be created to the item named target of the type indicated by role. The link’s text will be the same as target.

Cross-referencing ojbects:
^^^^^^^^^^^^^^^^^^^^^^^^^^

These roles are described with their respective domains:

- Python
- C
- C++
- JavaScript
- ReST