web-dev-qa-db-fra.com

Inclure ma démarque README dans Sphinx

Je voudrais inclure le README.md De mon projet dans ma documentation Sphinx comme dans sphinx peut-il créer un lien vers des documents qui ne se trouvent pas dans des répertoires sous le document racine? - qui est celui du Sphinx résultant documentation html Je clique sur un lien dans la table des matières sur la page d'accueil et accède au README.md.

Pour cela un document readme_link.rst Est créé qui contient les lignes

Readme File
-----------

.. include:: ../../README.md

et j'ajoute la ligne

README <readme_link>

dans le toctree de index.rst. Dans ce cas, mon README.md N'est pas analysé comme Markdown, mais simplement imprimé sur la page en tant que texte.

Je pensais qu'une autre idée pourrait être d'avoir un fichier de démarque à la place readme_link.md, Mais il n'y a aucun moyen d'inclure des fichiers avec une démarque.

Comment puis-je faire analyser mon fichier README.md en tant que démarque?

(Bien sûr, je ne veux pas le réécrire en tant que .rst.)

Pourquoi m2r ne fonctionne pas

J'ai essayé de suivre Rendu de la sortie du fichier markdown dans le fichier .rst , mais cela ne fonctionne pas. Mon README.md A des titres comme

# First heading

some text

## Second heading 1

some text

## Second heading 2

some text

et j'obtiens l'erreur WARNING: ../README.md:48: (SEVERE/4) Title level inconsistent:. Je comprends de Que signifie "Niveau de titre incohérent"? que j'ai besoin d'utiliser d'autres symboles - mais en les lisant, j'ai réalisé que la réponse se réfère aux symboles rst. Cela signifierait que mon fichier Readme de démarque n'a pas été transformé en rst.

PS: Quelqu'un d'autre qui a essayé quelque chose comme ça est https://muffinresearch.co.uk/selectively-including-parts-readme-rst-in-your-docs/

pythonmarkdownpython-sphinxrestructuredtext
15
Make42

Vous devez modifier votre readme_link.rst comme suit:

Readme File
===========

.. mdinclude:: ../../README.md

Notez que l'en-tête de section est désigné par = caractères plutôt que - personnages.

Il y a deux facteurs qui contribuent à cela.

Comment inclure les œuvres

La norme include (pas mdinclude) lit en fait le contenu du fichier source et copie simplement le texte brut à la place de la directive. mdinclude de M2R convertit d'abord le texte Markdown source en rst, puis, comme include, copie ce test à la place de la directive.

Par conséquent, au moment où le document rst est analysé, vous disposez d'un document rst complet des fichiers parent et inclus. Ce document complet doit être un document valide rst, ce qui nous amène au deuxième point ...

Les niveaux d'en-tête doivent être cohérents.

Pour rappel, le reStructuredText Spec explique:

Plutôt que d'imposer un nombre fixe et un ordre de styles de parure de titre de section, l'ordre appliqué sera l'ordre tel qu'il est rencontré. Le premier style rencontré sera un titre le plus externe (comme HTML H1), le deuxième style sera un sous-titre, le troisième sera un sous-titre, et ainsi de suite.

...

Tous les styles de titre de section ne doivent pas être utilisés, ni aucun style de titre de section spécifique ne doit être utilisé. Cependant, un document doit être cohérent dans son utilisation des titres de section: une fois qu'une hiérarchie des styles de titre est établie, les sections doivent utiliser cette hiérarchie.

Par conséquent, les niveaux d'en-tête de l'enfant inclus doivent être cohérents avec les niveaux d'en-tête du parent. Comme M2R génère un document rst, vous (en tant qu'utilisateur final) n'obtenez pas de spécificité quel caractère est utilisé pour définir chaque niveau de section. Par conséquent, pour maintenir la cohérence, vous devez utiliser le schéma défini par M2R :

  • Les premières marques de titre sont actuellement codées en dur et inchangeables.
    • H1: =, H2: -, H3: ^, H4: ~, H5: ", H6: #

Comme vous pouvez le voir, les en-têtes de niveau 1 utilisent le = les en-têtes de caractère et de niveau 2 utilisent le - personnage. Par conséquent, le même schéma doit être utilisé dans le parent readme_link.rst fichier (vous utilisiez l'inverse).

Une solution alternative

La spécification reStructuredText indique également:

Les styles d'ornement soulignés uniquement sont distincts des styles soulignés et soulignés qui utilisent le même caractère.

Par conséquent, vous pouvez utiliser des styles de soulignement et de soulignement dans votre document parent et peu importe les caractères que vous avez utilisés pour quel niveau car M2R semble uniquement utiliser des styles de soulignement uniquement. Cela aurait donc également fonctionné:

-----------
Readme File
-----------

.. mdinclude:: ../../README.md

Cela présente l'avantage supplémentaire (ou négatif - selon votre point de vue) que tous les en-têtes du document enfant inclus seront désormais d'un niveau inférieur à ce qu'ils seraient par eux-mêmes. Par conséquent, l'enfant est plus sémantiquement "imbriqué" dans le parent (plus d'un h1 dans un seul document HTML est souvent considéré comme non sémantique bien qu'il soit techniquement "valide"). Bien sûr, cela peut ou non être ce que vous voulez, c'est pourquoi il est qualifié de "solution alternative".

12
Waylan

Il existe une autre approche, si vous souhaitez uniquement inclure un document de démarque dans votre projet en tant que fichier distinct (et n'avez pas besoin d'incorporer le contenu de ce fichier dans un .rst fichier):

1. Assurez-vous que vous disposez des prérequis nécessaires

(Ces étapes sont également requises pour la réponse acceptée.)

1.1 Assurez-vous que le rendu de démarque est installé:

$ pip install -U sphinx>=1.8.3 recommonmark>=0.5.0

1.2 Ajoutez recommonmark à la liste de extensions dans conf.py

1.3 Créez un lien symbolique vers votre fichier de démarque

$ cd docs             # or docs/source
$ ln -s ../README.md  # or to ../../README.md if using docs/source

2. Incluez le fichier de démarque requis dans vos documents

Liez le fichier dans votre toctree:

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   source/README.md
11
Shon