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:

bisogna creare un file requirements.txt che ha il seguente contenuto:

sphinx-rtd-theme
sphinx
recommonmark
markdown
sphinx-markdown-tables

bisogna aggiungere nel file conf.py le seguenti istruzioni.

Dopo import sys, os inserire il seguente codice:

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']