Как задокументировать свой проект Django с помощью инструмента Sphinx

kak zadokumentirovat svoj proekt django s pomoshhyu instrumenta

Недавно я посетил компанию, где я приятно пообщался с одним из ее сотрудников. Мы говорили о технологиях и программировании. Затем мы затронули тему проектной документации. В частности, как React делает это автоматически, а Django нет. Это заставило меня подумать, что я должен сделать некоторую автоматическую документацию для моих проектов Django.

Я не мог найти никакой соответствующей документации о том, как это было сделано, так что мне понадобилось немного больше времени, чем я изначально планировал. Не потому, что это было трудно, а потому, что я обнаружил, что официальная документация и другие ресурсы Sphinx устарели или неясны.

Поэтому сегодня я сделал простое, но исчерпывающее руководство, объясняющее, как создать документацию Django с помощью инструмента документации Sphinx в Ubuntu.

Установите Sphinx

Сначала вам следует войти в виртуальную среду для вашего проекта Django.

Установка Sphinx достаточно проста с помощью pip3 (pip для Python 3):

pip3 install sphinx

Создайте каталог документации

После установки Sphinx необходимо создать корневую папку документа. В этой папке будет храниться документация и другие файлы, которые вам понадобятся (изображения, страницы и т.д.).

Создайте корневую папку документа в главной папке проекта и назовите ее /docs.

Для запуска Sphinx запустите эту команду в папке /docs:

sphinx-quickstart

Теперь у вас будет много вариантов. В большинстве случаев можно просто повторно ввести параметр по умолчанию, но есть некоторые параметры, на которые нужно обратить внимание.

Вот как я ответил:

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


> 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

В папке вашего проекта найдите /docs/conf.py и внутри него, где-то в верхней части файла, найдите «#import os». Чуть-чуть под ним напишите это:

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

Теперь вы можете продлить двумя способами:

  1. Вы можете использовать сфинкс-апидок генерировать полностью автоматическую документацию, или
  2. Вы можете создать собственные модули, отображаемые в документации.

В этом уроке я намерен показать вам, как это сделать в обе стороны.

1. Сфинкс-апидок

Это более простой метод, где вам просто нужно перейти к вашей папке /docs и выполнить:

sphinx-apidoc -o . ..

Теперь вам нужно создать свою документацию, выполнив команду:

make html

Перейдите к Your_project_folder/docs/_build/html и открыт index.html. Это индексная страница вашей документации.

2. Создание собственных модулей

Это несколько более сложный способ, но он даст вам гораздо больше свободы в организации вашей документации.

Теперь вы захотите создать документацию о ваших взглядах, модулях и т.д. Но сначала позвольте мне показать вам простой пример, чтобы вы поняли логику этой части:

Зайдите в папку /docs и создайте новую папку с названием /modules. Внутри него создайте файл с именем all-about-me.rst:

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

Внутри all-about-me.rst напишите что-нибудь вроде этого:

############
All about me
############

I’m Goran Aviani, a Django developer.

Теперь вы создали что-нибудь, чтобы показать в своей документации, но все равно у вас нет фактического места, чтобы показать это. Вернитесь в папку /docs и откройте index.rst и просто подведите этот код

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

Добавьте это:

modules/all-about-me.rst

Сделайте так, чтобы между верхним кодом и добавленной строкой была пустая строка:

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

   modules/all-about-me.rst

Теперь вам нужно создать документацию. Измените местоположение на папку, содержащую Makefile (это папка /docs). Затем запустите в терминале:

make html

Вы найдете свою документацию в

Your_project_folder/docs/_build/html и откройте index.html

Вы можете сделать то же самое для своих представлений Django:

В папке /modules создайте файл views.rst.

touch views.rst

Внутри файла views.rst напишите это:

Views
======

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

Внутри index.rst просто под modules/all-about-me.rst добавьте это:

modules/views.rst

Теперь вам снова нужно создать свою документацию, запустив «make html» в вашей папке /docs:

make html

Поняли? Сначала вы создаете файл .rst, а затем размещаете его в index.rst, чтобы его можно было отобразить на странице index.html.

Вы можете сделать то же самое для своих моделей. Зайдите в папку /modules и создайте файл models.rst.

touch models.rst

Вы можете добавить что-то вроде своего файла models.rst:

Models
=======

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

Внутри index.rst просто под modules/views.rst вставьте:

modules/models.rst

В папке /docs запустите:

make html

Проверка документации

Вы можете проверить документацию, запустив этот код в папке /docs:

make linkcheck

Вуаль! Вы кончили!

Это мое первое общедоступное учебное пособие, поэтому дайте мне несколько хлопков, если вам нравится 🙂

Спасибо, что читаете! Просмотрите больше таких статей в моем профиле freeCodeCamp: и другие интересные вещи, которые я создаю на своей странице GitHub:

Добавить комментарий

Ваш адрес email не будет опубликован.