Sintassi del linguaggio Markdown (MD) per le finalità di ‘Read the Docs’

Questa pagina illustra alcune guide online per i requisiti che i file di tipo Markdown .MD devono possedere al fine di compilare le ‘builds’ su Read the Docs.

Infatti oltre al formato ReStructuredText .RST anche il formato MarkDown .MD può compilare le ‘builds’ su Read the Docs per la visualizzazione dei contenuti nelle pagine HTML.

Nota

Questa pagina di tutorial nasce dall’esperienza vissuta nel costruire il tutorial http://hfcqgis.readthedocs.io, una guida “per rispondere alle numerose richieste di aiuto sull’uso del calcolatore di campi e per colmare un vuoto sulla guida online di QGIS con esempi e molti screenshot”.

Sintassi di base del linguaggio Markdown https://www.markdownguide.org/basic-syntax
Basic writing and formatting syntax. Create sophisticated formatting for your prose and code on GitHub with simple syntax https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax#styling-text
Una breve guida al linguaggio Markdown https://www.html.it/articoli/markdown-guida-al-linguaggio
Un tool online per editare codice in Markdown https://stackedit.io/app#
Una guida Read the Docs sul linguaggio Markdown https://markdown-guide.readthedocs.io (con utili analisi comparative tra sintassi del linguaggio MarkDown e HTML)
Project documentation with Markdown https://www.mkdocs.org
markdown-it demo https://markdown-it.github.io/

Fare leggere i file in formato “.md” a Read the Docs

Come descritto in questa issue, si possono fare leggere file in formato ``.md `` a Read the Docs.

Azioni da effettuare:

  1. bisogna creare un file requirements.txt che ha il seguente contenuto:
1
2
3
4
5
sphinx-rtd-theme
sphinx
recommonmark
markdown
sphinx-markdown-tables
  1. bisogna aggiungere nel file conf.py le seguenti istruzioni.

Dopo import sys, os inserire il seguente codice:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
import recommonmark
from recommonmark.transform import AutoStructify
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
html_static_path = ['static']
def setup(app):
    # overrides for wide tables in RTD theme
    app.add_stylesheet('theme_overrides.css') # path relative to static

app.add_stylesheet('theme_overrides.css') # path relative to static
source_parsers = {
    '.md': 'recommonmark.parser.CommonMarkParser',
}

source_suffix = ['.rst', '.md']

extensions = ['sphinx.ext.ifconfig','sphinx_markdown_tables']

source_suffix = '.rst' si trasformerà in source_suffix = ['.rst', '.md']