Cómo documentar su proyecto Django usando la herramienta Sphinx

Recientemente visité una empresa donde tuve una agradable charla con uno de sus empleados. Hablamos de tecnología y programación. Luego tocamos el tema de la documentación del proyecto. Específicamente cómo React lo hace automáticamente pero Django no lo hace. Eso me hizo pensar que debería hacer una documentación automática para mis proyectos de Django.

No pude encontrar ninguna documentación relevante sobre cómo se hace, por lo que me tomó un poco más de lo planeado originalmente. No porque fuera difícil, sino porque descubrí que la documentación oficial de Sphinx y otros recursos están desactualizados u oscuros.

Así que hoy hice un tutorial simple pero completo que explica cómo hacer documentación de Django usando la herramienta de documentación Sphinx en Ubuntu.

Instalar Sphinx

Primero debe ingresar al entorno virtual para su proyecto Django.

La instalación de Sphinx es bastante sencilla usando pip3 (pip para Python 3):

pip3 install sphinx

Crea un directorio de documentación

Una vez que haya instalado Sphinx, deberá crear la carpeta raíz del documento. Esta carpeta contendrá su documentación y otros archivos que necesitará (imágenes, acerca de las páginas, etc.).

Cree la carpeta raíz de su documento en la carpeta principal de su proyecto y asígnele el nombre / docs.

Para iniciar Sphinx, ejecute este comando dentro de su carpeta / docs:

sphinx-quickstart

Ahora tendrás muchas opciones. En la mayoría de los casos, simplemente puede volver a escribir la opción predeterminada, pero hay algunas opciones a las que debe prestar atención.

Así es como respondí:

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.

Conexión Django

En la carpeta de su proyecto, busque /docs/conf.py y dentro de él, en algún lugar cerca de la parte superior del archivo, busque “#import os”. Justo debajo de él, escribe esto:

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

Ahora hay dos formas de proceder:

  1. Puedes usar sphinx-apidocpara generar documentación completamente automática, o
  2. Puede crear sus propios módulos que se mostrarán en la documentación.

En este tutorial te mostraré cómo hacerlo de ambas formas.

1. Sphinx-apidoc

Este es el método más simple en el que solo necesita navegar a su carpeta / docs y ejecutar:

sphinx-apidoc -o . ..

Ahora necesita crear su documentación ejecutando el comando:

make html

Vaya a Your_project_folder / docs / _build / html y abra index.html. Esta es la página de índice de su documentación.

2. Construyendo sus propios módulos

Esta es la forma un poco más complicada, pero le dará mucha más libertad para organizar su documentación.

Ahora querrás hacer documentación sobre tus vistas, módulos, etc. Pero primero déjame mostrarte un ejemplo sencillo, para que entiendas la lógica de esta parte:

Vaya a su carpeta / docs y cree una nueva carpeta llamada "/ modules". En su interior, cree un archivo llamado all-about-me.rst:

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

Dentro de todo-sobre-mí. Primero escribe algo como esto:

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

Ahora ha creado algo para mostrar en su documentación, pero aún no tiene un lugar real para mostrarlo. Regrese a la carpeta / docs y abra index.rst y simplemente debajo de este código

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

Agrega esto:

modules/all-about-me.rst

Haga que haya una línea en blanco entre el código superior y la línea agregada:

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

Ahora necesitas crear tu documentación. Cambie la ubicación a la carpeta que contiene el Makefile (que es la carpeta / docs). Luego ejecuta en la terminal:

make html

Encontrarás tu documentación en

Your_project_folder / docs / _build / html y abra index.html

Puede hacer lo mismo con sus vistas de Django:

Dentro de la carpeta / modules, cree el archivo views.rst.

touch views.rst

Dentro del archivo views.rst escribe esto:

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

Dentro de index.rst, justo debajo de modules / all-about-me.rst, agregue esto:

modules/views.rst

Ahora, nuevamente necesita crear su documentación ejecutando "make html" dentro de su carpeta / docs:

make html

¿Captar la idea? Primero crea el archivo .rst y luego lo coloca dentro de index.rst para que pueda mostrarse en la página index.html.

Puedes hacer lo mismo para tus modelos. Vaya a su carpeta / modules y cree el archivo models.rst.

touch models.rst

Puede agregar algo como esto en su archivo models.rst:

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

Dentro de index.rst justo debajo de modules / views.rst pegue:

modules/models.rst

Dentro de su carpeta / docs ejecute:

make html

Prueba de documentación

Puede probar su documentación ejecutando este código dentro de su carpeta / docs:

make linkcheck

¡Voilà! ¡Estás listo!

Este es mi primer tutorial público, así que dame algunas palmadas si te gusta :)

¡Gracias por leer! Vea más artículos como este en mi perfil de freeCodeCamp: //www.freecodecamp.org/news/author/goran/ y otras cosas divertidas que creo en mi página de GitHub: //github.com/GoranAviani