Skip to content
Snippets Groups Projects
Commit 52dfa740 authored by Françoise Conil's avatar Françoise Conil
Browse files

Remaniement de la partie Read the Docs, relecture

La partie Read the Docs était parfois ambigüe.
Reformulation également à la relecture des autres slides.
parent 8a73d7b3
No related branches found
No related tags found
No related merge requests found
......@@ -545,26 +545,42 @@ open source avec ~460 contributeurices.
**Read the docs**, [comme PyPI](https://blog.pypi.org/posts/2023-04-23-introducing-pypi-organizations/#increasing-sustainability-and-support),
a connu une forte augmentation du nombre de projets et d'utilisateurs en 2023 ^[[statistiques annuelles Read the Docs 2023](https://about.readthedocs.com/blog/2024/03/read-the-docs-2023-stats/)].
99% des projets utilisent git ^[[Arrêt du support de SVN, Mercurial et Bazaar](https://about.readthedocs.com/blog/2024/02/drop-support-for-subversion-mercurial-bazaar/)].
^[99% des projets utilisent git : [Arrêt du support de SVN, Mercurial et Bazaar](https://about.readthedocs.com/blog/2024/02/drop-support-for-subversion-mercurial-bazaar/)].
## Fonctionnement
La documentation est générée à chaque `push` `git` et `Read the docs` peut
afficher [plusieurs versions de la documentation](#plusieurs-versions-de-documentation).
La création d'un compte `Read the docs` est possible à partir d'un email / mot de passe
ou en s'authentifiant avec un compte `github.com`, `gitlab.com` ou `bitbucket.org`.
La génération de la documentation est déclenchée sur le serveur hébergeant le
repository via un [webhook](https://docs.readthedocs.io/en/stable/glossary.html#term-webhook)
^[Déclenché par exemple à chaque `push` `git`]
La création d'un compte `Read the docs` est possible à partir :
:::: {.columns}
- d'un email / mot de passe
- d'un compte `github.com`, `gitlab.com` ou `bitbucket.org`
::: {.column width="50%"}
![](images/rtd-github-webhook-triggering-events-1.png){title="GitHub webhook triggering event 1" height="200"}
:::
## tutorial
::: {.column width="50%"}
![](images/rtd-github-webhook-triggering-events-2.png){title="GitHub webhook triggering event 1" height="200"}
:::
::::
`Read the docs` peut afficher [plusieurs versions de la documentation](#plusieurs-versions-de-documentation).
## Tutorial (GitHub)
Le [tutorial](https://docs.readthedocs.io/en/stable/tutorial/index.html) montre :
- les étapes pour créer un projet GitHub à partir d'un [template d'exemple](https://github.com/readthedocs/tutorial-template/),
- comment se créer un compte `Read the docs` en s'authentifiant avec `GitHub`
- comment importer simplement son projet sur `Read the docs`
- les étapes pour créer un projet `GitHub` à partir d'un [template d'exemple](https://github.com/readthedocs/tutorial-template/),
- comment se créer un compte `Read the docs` en s'authentifiant avec `GitHub`,
ce qui peut se faire également à partir de `GitLab` ou `Bitbucket` ^[[How to
automatically configure a Git repository](https://docs.readthedocs.io/en/stable/guides/setup/git-repo-automatic.html)]
- comment importer simplement son projet sur `Read the docs` ^[Tutorial : [Importing the project to Read the Docs](https://docs.readthedocs.io/en/stable/tutorial/index.html#importing-the-project-to-read-the-docs)]
- comment configurer la génération de la documentation à l'aide d'un fichier
`.readthedocs.yaml` placé à la racine du repository ^[Tutorial : [Adding a configuration file](https://docs.readthedocs.io/en/stable/tutorial/index.html#adding-a-configuration-file)]
La méthode proposée facilite la création de projets sur `Read the docs` et la
configuration des [webhook](https://docs.readthedocs.io/en/stable/glossary.html#term-webhook)
......@@ -572,7 +588,9 @@ associés sur GitHub, mais il est possible de procéder manuellement.
## Configuration manuelle
[How to manually configure a Git repository integration](https://docs.readthedocs.io/en/stable/guides/setup/git-repo-manual.html)
Comment configurer Read the Docs avec un repository sur GitHub, Bitbucket,
GitLab, Gitea ou autre : [How to manually configure a Git repository
integration](https://docs.readthedocs.io/en/stable/guides/setup/git-repo-manual.html)
## Fichier de configuration `.readthedocs.yaml`
......@@ -607,6 +625,8 @@ python:
---
Descriptions des éléments du fichier `.readthedocs.yaml`
- [build.os](https://docs.readthedocs.io/en/stable/config-file/v2.html#build-os) :
spécifie l'image Docker à utiliser pour la documentation (choix entre 2
version d'une Ubuntu LTS)
......@@ -836,7 +856,7 @@ vidéo :
### Documentation d'API : sphinx-apidoc 1/2
La commande `sphinx-apidoc` ^[[man sphinx-apidoc](https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html)]
peut générer une documentation complète d'API à l'aide des directives `autodoc` :
peut générer une documentation complète d'`API` à l'aide des directives `autodoc` :
```{.bash}
$ sphinx-apidoc -f -T -d 2 -M -o docs/source/api src/ntt
......@@ -872,10 +892,12 @@ ntt
### Documentation d'API : sphinx-apidoc 2/2
Il suffit d'inclure une référence vers **le fichier généré pour le package**,
ici `source/api/ntt.rst`, dans la documentation.
Inclure une référence vers le fichier généré comme point d'entrée de la
documentation d'`API` du package, ici `source/api/ntt.rst`, dans la
documentation.
Par exemple, dans le fichier racine `index.rst` ^[Voir la slide sur la [table des matières](#table-des-matières)] :
Exemple d'inclusion dans le fichier racine `index.rst` ^[Voir la slide sur la
[table des matières](#table-des-matières)] :
```{.rest code-line-numbers="6"}
.. toctree::
......@@ -896,7 +918,7 @@ permet d'ajouter des références ^[Voir la documentation Sphinx [cross-refenren
et la section [Ajouter des références](#ajouter-des-références)]
vers des documentations externes :
- explicitement avec le role `external`
- explicitement avec le role `:external:`
- implicitement en solution de repli quand une référence n'est pas trouvée dans
la documentation courante
......@@ -920,20 +942,14 @@ On peut ensuite ajouter des liens vers la documentation Python par exemple :
Voir :external:ref:`re-syntax` pour la syntaxe des expressions régulières en Python.
```
::: {.callout-note}
L'utilisation d'`:external:` est optionnelle, Sphinx recherche la référence
dans les documentations externe si il ne la trouve pas dans la documentation
courante.
:::
On peut mettre un lien vers la documentation d'une fonction :
```{.rest}
Voir la documentation de la fonction :external:py:func:`re.match`
```
Pour faire référence à la définition présente dans la documentation du module
`re` :
Pour faire référence à la définition présente dans la documentation `Python` du
module `re` :
```{.rest}
.. function:: match(pattern, string, flags=0)
......@@ -973,13 +989,15 @@ Ce qui explique que l'on trouve peu d'utilisation de ce mot-clé : 44 fichiers r
## nbsphinx, nbsphinx-link
Permet l'intégration de notebooks à la documentation, présenté par Loïc Gouarin
^[[Présentation 2023 sur le packaging Python](https://gouarin.github.io/python-packaging-2023/sphinx#nbsphinx)]
^[10.4k fichiers `conf.py` trouvés sur GitHub pour la requête `nbsphinx path:conf.py`]
Permet l'intégration de notebooks à la documentation ^[[Présentation 2023 sur
le packaging Python](https://gouarin.github.io/python-packaging-2023/sphinx#nbsphinx) par
Loïc Gouarin] ^[10.4k fichiers `conf.py` trouvés sur GitHub pour la requête
`nbsphinx path:conf.py`]
- [nbsphinx](https://nbsphinx.readthedocs.io/en/0.9.3/index.html) : Jupyter
Notebook Tools for Sphinx. `nbsphinx` is a `Sphinx extension` that provides a
source parser for `*.ipynb` files
Notebook Tools for Sphinx. \
`nbsphinx` is a `Sphinx extension` that provides a source parser for `*.ipynb`
files
- [nbsphinx-link](https://nbsphinx-link.readthedocs.io/en/latest/) is a
`Sphinx extension` built on `nbsphinx` that allows you to include Jupyter
notebooks that sit outside your sphinx source directory in your documentation
......@@ -1271,7 +1289,7 @@ Bob <- Alice : Yet another authentication Response
Bon le rendu n'est pas encore convainquant, mais un jour ...
:::
# Thèmes HTML
# Thèmes HTML pour Sphinx
## Options de configuration de la sortie HTML
......@@ -1394,15 +1412,15 @@ pour ajouter des composants d'interface utilisateur ^[[grids](https://sphinx-des
[tabs](https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/web-components.html#tabs),
[badges and button-links](https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/web-components.html#badges-and-button-links)
and [icons](https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html#inline-icons)]
et faciliter la création de contenus.
et améliorer la création de contenus.
Cela nécessite d'installer le package `sphinx-design`
Il faut installer le package `sphinx-design` :
```{.bash}
$ pip install sphinx-design
```
et de déclarer l'extension `sphinx_design` dans le fichier `conf.py`
et déclarer l'extension `sphinx_design` dans le fichier `conf.py`
```{.python code-line-numbers="3"}
extensions = ['sphinx.ext.autodoc',
......@@ -1712,7 +1730,7 @@ Voici le contenu de mon avertissement. {sup}`1`
```
````
Il faut **ajouter l'option** suivante ^[[Code fences using
Il faut **ajouter l'option** `myst_enable_extensions` ^[[Code fences using
colons](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-colon-fence)]
au fichier `conf.py` pour que la syntaxe callout / admonitions soit supportée
^[5.5k fichiers `conf.py` trouvés sur GitHub pour la requête `myst_enable_extensions path:conf.py`] :
......@@ -1955,7 +1973,7 @@ Par défaut, Sphinx propose les domaines [C](https://www.sphinx-doc.org/en/maste
```{.rest}
.. c:function:: void hook_register(name, int (*callback)(...))
.. c:macro:`LV_COLOR_DEPTH` ``8``: 3 x image width x image height
.. c:macro:: `LV_COLOR_DEPTH` ``8``: 3 x image width x image height
.. cpp:class:: template<K> nsTHashSet<K>
.. cpp:function:: V& LookupOrInsert(KeyType aKey, Args&&... aArgs) const
......
images/rtd-github-webhook-triggering-events-1.png

33.5 KiB

images/rtd-github-webhook-triggering-events-2.png

36.6 KiB

0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment