Sådan dokumenteres dit Django-projekt ved hjælp af Sphinx-værktøjet

Jeg besøgte for nylig et firma, hvor jeg havde en god snak med en af ​​dens ansatte. Vi talte om teknologi og programmering. Derefter berørte vi emnet for projektdokumentation. Specifikt hvordan React gør det automatisk, men Django ikke. Det fik mig til at tænke, at jeg skulle lave nogle automatiske dokumenter til mine Django-projekter.

Jeg kunne ikke finde nogen relevant dokumentation for, hvordan det blev gjort, så det tog mig lidt længere tid, end jeg oprindeligt planlagde. Ikke fordi det var svært, men fordi jeg fandt ud af, at Sphinx officielle dokumentation og andre ressourcer var forældede eller uklare.

Så i dag har jeg lavet en enkel, men omfattende tutorial, der forklarer, hvordan man laver Django-dokumentation ved hjælp af Sphinx-dokumentationsværktøjet i Ubuntu.

Installer Sphinx

Først skal du gå ind i det virtuelle miljø til dit Django-projekt.

Installation af Sphinx er ret ligetil ved hjælp af pip3 (pip til Python 3):

pip3 install sphinx

Opret en dokumentationsmappe

Når du har installeret Sphinx, skal du oprette dokumentets rodmappe. Denne mappe indeholder din dokumentation og andre filer, du har brug for (billeder, om sider osv. ...).

Opret din dokumentrodmappe i projektets hovedmappe, og navngiv den / docs.

For at starte Sphinx skal du køre denne kommando inde i din / docs-mappe:

sphinx-quickstart

Du har mange muligheder nu. I de fleste tilfælde kan du blot indtaste standardindstillingen igen, men der er nogle muligheder, du skal være opmærksom på.

Sådan svarede jeg:

Welcome to the Sphinx 1.7.5 quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). Selected root path: . You have two options for placing the build directory for Sphinx output. Either, you use a directory “_build” within the root path, or you separate “source” and “build” directories within the root path. > Separate source and build directories (y/n) [n]: n Inside the root directory, two more directories will be created; “_templates” for custom HTML templates and “_static” for custom stylesheets and other static files. You can enter another prefix (such as “.”) to replace the underscore. > Name prefix for templates and static dir [_]: _ The project name will occur in several places in the built documentation. > Project name: Your_project_name > Author name(s): Goran Aviani > Project release []: 1.0 If the documents are to be written in a language other than English, you can select a language here by its language code. Sphinx will then translate text that it generates into that language. For a list of supported codes, see //sphinx-doc.org/config.html#confval-language. > Project language [en]: en The file name suffix for source files. Commonly, this is either “.txt” or “.rst”. Only files with this suffix are considered documents. > Source file suffix [.rst]: .rst One document is special in that it is considered the top node of the “contents tree”, that is, it is the root of the hierarchical structure of the documents. Normally, this is “index”, but if your “index” document is a custom template, you can also set this to another filename. > Name of your master document (without suffix) [index]: index Sphinx can also add configuration for epub output: > Do you want to use the epub builder (y/n) [n]: n Indicate which of the following Sphinx extensions should be enabled: > autodoc: automatically insert docstrings from modules (y/n) [n]: y > doctest: automatically test code snippets in doctest blocks (y/n) [n]: y > intersphinx: link between Sphinx documentation of different projects (y/n) [n]: n > todo: write “todo” entries that can be shown or hidden on build (y/n) [n]: y > coverage: checks for documentation coverage (y/n) [n]: y > imgmath: include math, rendered as PNG or SVG images (y/n) [n]: y > mathjax: include math, rendered in the browser by MathJax (y/n) [n]: n > ifconfig: conditional inclusion of content based on config values (y/n) [n]: n > viewcode: include links to the source code of documented Python objects (y/n) [n]: n > githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: n A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html’ instead of invoking sphinx-build directly. > Create Makefile? (y/n) [y]: y > Create Windows command file? (y/n) [y]: y Creating file ./conf.py. Creating file ./index.rst. Creating file ./Makefile. Creating file ./make.bat. Finished: An initial directory structure has been created. You should now populate your master file ./index.rst and create other documentation source files. Use the Makefile to build the docs, like so: make builder where “builder” is one of the supported builders, e.g. html, latex or linkcheck.

Django-forbindelse

Find /docs/conf.py i din projektmappe, og inden i den, et eller andet sted øverst i filen, skal du finde “#import os”. Lige under det, skriv dette:

import os import sys import django sys.path.insert(0, os.path.abspath('..')) os.environ['DJANGO_SETTINGS_MODULE'] = 'Your_project_name.settings' django.setup()

Nu er der to måder, du kan gå videre på:

  1. Du kan bruge sfinx-apidocat generere fuldstændig automatisk dokumentation, eller
  2. Du kan oprette dine egne moduler, der vises i dokumentationen.

I denne vejledning vil jeg vise dig, hvordan du gør det begge veje.

1. Sphinx-apidoc

Dette er den enklere metode, hvor du bare skal navigere til din / docs-mappe og udføre:

sphinx-apidoc -o . ..

Nu skal du opbygge din dokumentation ved at køre kommandoen:

make html

Naviger til Your_project_folder / docs / _build / html og åbn index.html. Dette er indekssiden i din dokumentation.

2. Bygge dine egne moduler

Dette er den lidt mere komplicerede måde, men giver dig meget mere frihed til at organisere din dokumentation.

Nu vil du gerne lave dokumentation om dine synspunkter, moduler osv. Men lad mig først vise dig et let eksempel, bare så du forstår logikken i denne del:

Gå i din / docs-mappe, og opret en ny mappe med navnet “/ modules”. Inde i det opretter du en fil med navnet all-about-me.rst:

mkdir modulesf touch modules/all-about-me.rst

Inde i alt-om-mig.rst skriv noget som dette:

############ All about me ############ I’m Goran Aviani, a Django developer.

Nu har du oprettet noget at vise i din dokumentation, men du har stadig ikke et faktisk sted at vise det. Gå tilbage til / docs-mappen, og åbn index.rst og bare bælg denne kode

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

Tilføj dette:

modules/all-about-me.rst

Gør det, så der er en tom linje mellem den øverste kode og den tilføjede linje:

.. toctree:: :maxdepth: 2 :caption: Contents: modules/all-about-me.rst

Nu skal du opbygge din dokumentation. Skift placeringen til den mappe, der indeholder Makefile (det er mappen / docs). Kør derefter i terminalen:

make html

Du finder din dokumentation i

Din_projektmappe / docs / _build / html og åben index.html

Du kan gøre det samme for dine Django-visninger:

Opret filen views.rst inde i mappen / modules.

touch views.rst

Inde i views.rst-filen skriv dette:

Views ====== .. automodule:: yourapp.views :members: :undoc-members:

Inde i index.rst, lige under moduler / alt-om-mig.rst, tilføj dette:

modules/views.rst

Nu skal du igen oprette din dokumentation ved at køre "make html" inde i din / docs-mappe:

make html

Få idéen? Først opretter du .rst-filen, og derefter placerer du den i index.rst, så den kan vises på index.html-siden.

Du kan lave det samme til dine modeller. Gå i mappen / moduler, og opret models.rst-fil.

touch models.rst

Du kan tilføje noget som dette i din models.rst-fil:

Models ======= .. automodule:: yourapp.models :members: :undoc-members:

Inde i index.rst lige under moduler / views.rst pasta:

modules/models.rst

Inde i din / docs-mappe køres:

make html

Dokumentationstest

Du kan teste din dokumentation ved at køre denne kode i mappen / docs:

make linkcheck

Voilà! Du er færdig!

Dette er min første offentlige tutorial, så giv mig et par klapper, hvis du kan lide det :)

Tak fordi du læste! Tjek flere artikler som denne på min freeCodeCamp-profil: //www.freecodecamp.org/news/author/goran/ og andre sjove ting, jeg bygger på min GitHub-side: //github.com/GoranAviani