Construire la documentation du produit avec MKDOCS

Il y a une maxime populaire selon laquelle «un produit est aussi bon que sa documentation». Cela est vrai pour les logiciels que pour les produits physiques.

En tant que petit développeur indépendant qui ne se spécialise pas dans la conception frontale, j'embauche souvent un pigiste pour construire mon site Web de produit - qui, bien sûr, comprend généralement une section de documentation.

Une section de documentation peut prendre un peu de temps et d'argent à construire, même pour un produit simple, il serait donc bien de ne pas avoir à réinventer la roue pour chaque site. Heureusement, il y a un moyen.

Les plats clés

• MKDOCS est un générateur de sites statique gratuit idéal pour construire la documentation du projet; Il est léger, facile à héberger et peut être utilisé pour un site autonome ou une section de documentation d'un site plus grand.
• Pour utiliser MKDOCS, Python et PIP (un gestionnaire de packages Python) doit être installé sur votre ordinateur; MKDOCS est installé localement sur votre ordinateur, vous permettant de créer votre documentation hors ligne.
• MKDOCS permet la personnalisation avec une variété de thèmes et la possibilité d'ajouter de nouvelles pages via le fichier de configuration mkdocs.yml; Il comprend également un serveur Web intégré pour la prévisualisation locale de la documentation.
• La documentation construite avec les MKDOC peut être hébergée gratuitement sur des services comme les pages GitHub et lire les documents, ou sur votre propre serveur; MKDOCS prend également en charge directement le déploiement sur ces plateformes.

Présentation des Mkdocs

MKDOCS est un générateur de sites statique gratuit destiné à construire la documentation du projet. Il peut être utilisé pour générer un site autonome, ou simplement une section de documentation d'un site plus grand.

Parce que les MKDOC produisent des fichiers statiques, votre documentation est légère et facile à héberger - en utilisant des services gratuits tels que les pages GitHub et lire les documents - ou bien sûr sur votre propre serveur.

Dans cet article, je présenterai MKDOCS, vous montrant comment l'installer, construire une documentation avec lui et enfin héberger la documentation générée sur un serveur Web.

Pour avoir une idée du type de documentation que MKDOC produit, jetez un œil à ma documentation de plugin WordPress ProfilePress, qui est construite avec des MKDOC en utilisant le thème DOCS Read the Docs.

Mkdocs est écrit en python. Les fichiers source de documentation sont écrits dans Markdown et configurés avec un seul fichier de configuration YAML.

Pour créer une documentation avec MKDOC, vous devez l'installer localement sur votre ordinateur. Alors, regardons comment l'installer.

Installation de Python et Mkdocs

générateurs de sites statiques comme Jekyll (utilisé principalement pour les blogs et construit sur Ruby) et les MKDOC nécessitent des côtelettes en ligne de commande, alors soyez averti. Cependant, pour ceux qui n'ont pas l'habitude de travailler avec la ligne de commande, je vous encourage à lire et à l'essayer, car ce n'est pas aussi mauvais qu'il n'y paraît!

Installation de Python et Pip

Pour installer des MKDOC, vous devez avoir installé Python et Pip (un gestionnaire de packages Python) dans votre ordinateur. Ils peuvent déjà être installés sur votre ordinateur. Si vous avez installé Python 3.4 ou ultérieur, vous avez probablement installé PIP. (Voir le guide d'installation Python pour les instructions complètes.)

Pour installer Python sur une distribution Linux telle que Ubuntu, consultez ce thread Stackoverflow ou effectuez une recherche Google pour votre distribution.

Pour Windows, téléchargez votre installateur de version préférée et exécutez le fichier pour installer Python.

Alternativement, si le gestionnaire de packages chocolatés installé dans votre machine, exécutez Choco Installez Python.

Pour vérifier que votre distribution Python a installé PIP, exécutez la commande pip --version. Sinon, exécutez Python Get-Pip.py ou Choco Installer Pip via Chocolatey pour l'installer.

Installation de mkdocs

Maintenant que Python et PIP sont installés, exécutez PIP installe MKDOCS pour installer Mkdocs.

Pour confirmer que tout va bien, exécutez les MKDOC aident à essayer la commande mkdocs.

Si vous êtes sous Windows et que la commande MKDOCS n'est pas vivante, assurez-vous d'ajouter C: Path-to-python-Folderscripts to Path Environmental Variable.

Construire la documentation

Maintenant que vous avez configuré Python et Mkdocs, vous pouvez continuer votre documentation réelle.

Tout d'abord, créez un projet pour la documentation (appelons-le SP-DOC) et accédez au dossier créé:

$ mkdocs new sp-doc
$ cd sp-doc

Le dossier du projet généré contiendra un dossier DOCS - où les fichiers de démarrage de la documentation seront stockés - et le fichier de configuration mkdocs.yml.

Voici la structure du répertoire:

|-- docs              # MD doc pages
    |-- index.md
|-- mkdocs.yml        # config file

Ajoutez la configuration du minimum nu suivant au fichier mkdocs.yml:

site_name: SitePoint Documentation
site_description: Description of the documentation
theme: readthedocs
pages:
- ['index.md', 'Index']

MKDOCS expédient avec un certain nombre de thèmes, comme «Mkdocs», «Lisez les documents» et «bootstrap». Dites que vous avez l'intention d'utiliser le thème par défaut. Dans ce cas, remplacez simplement ReadTheDocs par des MKDOC dans le code ci-dessus.

La configuration des pages est utilisée pour déterminer l'ensemble des pages qui doivent être construites pour la documentation et le menu de navigation.

Les fichiers de marque ajoutés aux pages doivent être relatifs au dossier DOCS. Par exemple, si vous avez créé un nouveau dossier appelé config dans le répertoire DOCS et que vous avez ajouté un fichier setup.md, voici comment vous ajouteriez aux pages de la configuration du fichier mkdocs.yml:

site_name: SitePoint Documentation
site_description: Description of the description
theme: readthedocs
pages:
- ['index.md', 'Index']
- ['start.md', 'Get Started']
- ['config/setup.md', 'Configuration', 'Setup']
- ['config/debug.md', 'Configuration', 'Debug']

Cela crée de nouvelles pages qui apparaissent automatiquement dans notre menu de documentation. Premièrement, il y a une page start.md, avec le titre «Get Starcing».

Nous avons également ajouté une nouvelle section au menu de documentation intitulé "Configuration", sous lequel il y a un lien vers de nouvelles pages de configuration et de débogage.

MKDOCS comprend un serveur Web intégré, vous pouvez donc prévisualiser votre documentation localement lorsque vous y travaillez.

Pour démarrer le serveur Web, assurez-vous que vous êtes dans le répertoire où réside le fichier de configuration mkdocs.yml, puis exécutez la commande Mkdocs Serve.

Visitez http://127.0.0.1:8000 dans votre navigateur pour afficher la documentation:

Si vous êtes satisfait de ce que vous avez créé, exécutez MKDOCS Build pour générer les fichiers statiques pour la documentation qui sera enregistrée dans le répertoire du site.

Vous pouvez copier les fichiers statiques et les héberger sur un serveur Web de votre choix de prendre la documentation en direct.

Dans la section suivante, nous apprendrons à déployer des MKDocs pour lire les pages Docs et GitHub.

Déploiement de Mkdocs

Tout d'abord, créez un référentiel github (ou bitbucket) pour stocker les fichiers.

Exécutez les commandes suivantes pour se déployer sur gitHub où https://github.com/collizo4sky/sitepoint_mkdocs est mon propre Mkdocs Repo:

$ mkdocs new sp-doc
$ cd sp-doc

Déployons maintenant nos fichiers de documentation pour lire les documents, un service de documentation gratuit.

Lisez les documents

Tout d'abord, créez un compte si vous n'en avez pas et vous connectez.

Cliquez sur le bouton Importer un projet ou cliquez sur l'élément d'ajout du menu du projet.

Vous pouvez choisir de connecter votre compte GitHub ou Bitbucket pour lire les documents pour importer l'intégralité de votre projet. Au lieu de cela, nous irons avec l'importation manuelle, en cliquant sur le bouton Importer manuellement.

Remplissez le formulaire comme indiqué dans l'image ci-dessous:

En importation avec succès des documents de GitHub, vous serez redirigé vers la page du projet:

Vous pouvez afficher notre documentation générée sur http://sitepoint-doc.readthedocs.org/en/latest/.

Si vous voulez que la documentation sur un sous-domaine, indiquez un enregistrement CNAME dans votre DNS au sous-domaine de votre projet.

Par exemple, pour rendre la documentation disponible sur docs.sitepoint.com, créez un enregistrement CNAME pointant vers SitePoint-doc.readthedocs.org.

pages github

Voyons maintenant comment héberger notre documentation sur les pages GitHub, un autre service d'hébergement gratuit.

Assurez-vous que vous êtes sur la branche de travail du référentiel GIT - qui est la branche principale de notre cas.

Exécutez la commande mkdocs gh-deploy - Clean

Dans les coulisses, cette commande construira vos documents et les engagera dans la branche GH-Pages, puis pousse la branche vers GitHub.

Voici une démo de nos documents de point de point sur les pages GitHub.

d'autres fournisseurs

Tout fournisseur d'hébergement pouvant servir des fichiers statiques peut être utilisé pour desservir la documentation générée par les MKDOC. Les directives suivantes devraient fournir une assistance générale.

Lorsque vous créez votre site à l'aide de la commande MKDOCS Build, tous les fichiers sont écrits dans le répertoire attribué à l'option de configuration Site_dir (par défaut sur «Site») dans votre fichier de configuration mkdocs.yaml.

Copiez simplement le contenu de ce répertoire dans le répertoire racine du serveur de votre fournisseur d'hébergement et vous avez terminé. Ou, si vos documents ne seront qu'une sous-section de votre site, déplacez les fichiers vers un sous-dossier désigné.

Résumé

Dans ce didacticiel, nous avons appris à créer une documentation avec MKDOCS, un générateur de site Web statique Python, ainsi que comment déployer et héberger la documentation gratuitement sur des pages GitHub et lire les documents.

Avez-vous déjà utilisé des MKDOC? Sinon, envisageriez-vous de l'utiliser? Comment gérez-vous actuellement la portion de documentation à vos utilisateurs? J'aimerais entendre vos commentaires ou répondre à toutes les questions que vous pourriez avoir.

Questions fréquemment posées (FAQ) sur la construction de la documentation des produits avec MKDOCS

Quelles sont les conditions préalables à l'utilisation de mkdocs?

Pour utiliser des MKDOC, vous devez installer Python sur votre système. MKDOCS prend en charge les versions Python 2.7, 3.5, 3,6, 3,7, 3,8 et Pypy. Vous pouvez vérifier votre version Python en tapant Python - Version dans votre invite de commande. Si Python est installé avec succès, le numéro de version s'affiche. Sinon, vous devez d'abord installer Python. Une fois Python installé, vous pouvez installer des MKDOC à l'aide de PIP, le programme d'installation du package Python. Tapez PIP Installer MKDOCS dans votre invite de commande pour installer Mkdocs.

Comment puis-je personnaliser l'apparence de mon site MKDOCS?

MKDOCS utilise des thèmes pour contrôler l'apparence du site. Le thème par défaut est appelé «MKDOCS», mais il existe de nombreux autres thèmes disponibles. Vous pouvez modifier le thème en modifiant le fichier de configuration mkdocs.yml. Dans la section du thème, remplacez les MKDOC par le nom de votre thème souhaité. Certains thèmes permettent également une personnalisation supplémentaire en ajoutant un fichier CSS ou JavaScript personnalisé.

Comment ajouter une nouvelle page à mon site MKDOCS?

Pour ajouter une nouvelle page, créez d'abord un nouveau démarrage fichier dans votre répertoire DOCS. Le nom du fichier sera utilisé comme URL pour la page. Ensuite, ajoutez une nouvelle entrée à la section Pages de votre fichier de configuration Mkdocs.yml. Le format est - [«Titre de la page», «filename.md»]. Le titre de la page sera utilisé comme texte de lien dans le menu de navigation.

Comment déployer mon site MKDOCS?

MKDOCS Inclut une commande de déploiement intégrée pour les pages GitHub. Exécutez simplement MKDOCS GH-Deploi à partir de votre invite de commande, et MKDOCS créera votre site et le poussera vers la branche GH-Pages de votre référentiel GitHub. Si vous souhaitez déployer sur un autre fournisseur, vous devrez créer le site avec MKDOCS Build, puis télécharger manuellement les fichiers du site.

Puis-je utiliser des MKDOC avec Lire les documents?

Oui, MkDocs est entièrement compatible avec Read the Docs, une plate-forme d'hébergement de documentation populaire. Pour utiliser des MKDOC avec Lire les documents, vous devez créer un fichier de configuration .readthedocs.yml dans la racine de votre référentiel et spécifier les MKDOC comme type de documentation.

Comment mettre à jour MKDOCS?

Vous pouvez mettre à jour MKDOCS en exécutant PIP Installer –Upgrade MKDOCS dans votre invite de commande. Cela téléchargera et installera la dernière version de Mkdocs.

Puis-je utiliser MKDOCS pour la documentation privée?

Oui, vous pouvez utiliser MKDOCS pour une documentation privée. Cependant, si vous utilisez le déploiement des pages GitHub intégré, votre documentation sera accessible au public. Si vous devez garder votre documentation privée, vous pouvez utiliser un autre fournisseur d'hébergement qui prend en charge la protection des mots de passe ou le contrôle d'accès.

Comment ajouter une fonction de recherche à mon site MKDOCS?

La plupart des MKDOC MKDOCS? Les thèmes incluent une fonction de recherche intégrée. Si votre thème n'inclut pas la recherche, ou si vous souhaitez utiliser un autre fournisseur de recherche, vous pouvez ajouter un plugin de recherche à votre fichier de configuration mkdocs.yml.

Puis-je utiliser des MKDOC pour générer un PDF de mon mon La documentation?

MKDOCS est conçue pour générer des sites Web HTML, pas des PDF. Cependant, il existe des outils et services tiers qui peuvent convertir votre site MKDOCS en PDF.

Comment ajouter un menu de navigation à mon site MKDOCS?

Le menu de navigation est automatiquement généré automatiquement Dans la section Pages de votre fichier de configuration Mkdocs.yml. Chaque entrée dans la section Pages devient un lien dans le menu de navigation. L'ordre des liens correspond à l'ordre des entrées dans la section des pages.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!