Создание демонстрационного проекта

Наш демонстрационный проект будет содержать информацию о The Zen of Python.

Чтобы создать демонстрационный проект:

  1. Создайте каталог для демонстрационного проекта:

    mkdir zen

  2. Перейдите в папку проекта:

    cd zen

  3. Создайте новый проект sphinx с помощью sphinx-quickstart:

    sphinx-quickstart

    Эта команда запускает утилиту Sphinx quickstart, которая задает вам несколько вопросов о настройках вашего проекта. Укажите следующие параметры:

    > Separate source and build directories (y/n) [n]: n

    > Project name: The Zen of Python

    > Author name(s): authoress

    > Project release []: 1.0.0

    > Project language [en]: en

    Вы можете указать свои настройки, но обязательно установите язык проекта на английский (en).

    После того, как вы ответите на все вопросы, утилита Sphinx quickstart создаст проект:

    zen
│   conf.py
│   index.rst
│   make.bat
│   Makefile
│   tree.txt
│
├───_build
├───_static
└───_templates

Если вы знакомы со Sphinx, вы уже знаете о index.rst, conf.py и других файлах проекта по умолчанию.

Добавление содержимого

Откройте index.rst в любом текстовом редакторе и замените его содержимое следующим:

The Zen of Python
=================

.. toctree::
   :hidden:
   :glob:

   easter-egg.rst

*By Tim Peters*

Beautiful is better than ugly.

Explicit is better than implicit.

Simple is better than complex.

Complex is better than complicated.

Flat is better than nested.

Sparse is better than dense.

Readability counts.

Special cases aren't special enough to break the rules.

Although practicality beats purity.

Errors should never pass silently.

Unless explicitly silenced.

In the face of ambiguity, refuse the temptation to guess.

There should be one-- and preferably only one --obvious way to do it.

Although that way may not be obvious at first unless you're Dutch.

Now is better than never.

Although never is often better than \*right\* now.

If the implementation is hard to explain, it's a bad idea.

If the implementation is easy to explain, it may be a good idea.

Namespaces are one honking great idea -- let's do more of those!

Мы добавили easter-egg.rst в toctree, а это значит, что мы должны создать этот файл в папке проекта. После того, как вы создали файл (он должен быть кодирован в UTF-8), поместите в него этот текст:

Easter Egg
==========

In Python interactive prompt, run:

::

>>> import this

Enjoy your easter egg!

Вы можете скачать архив, содержащий оба файла.

Добавление изображений

Чтобы добавить изображения в демонстрационный проект:

  1. Загрузите архив, содержащий два изображения: logo.png (логотип демонстрационного проекта) и egg.png (изображение яйца).

  2. Разархивируйте архив и поместите оба файла в каталог _static демонстрационного проекта.

  3. Откройте conf.py, найдите раздел Options for HTML output. Добавьте html_theme_options, содержащий logo.png, после html_theme, вот так:

html_theme = 'alabaster'

html_theme_options = {

'logo' : 'logo.png'

}

  1. Добавьте egg.png в easter-egg.rst, вот так:

Enjoy your easter egg!

.. image:: _static/egg.png

Вы можете загрузить conf.py и easter-egg.rst, которые уже содержат оба дополнения.

Обратите внимание, что если вы указали собственные настройки при создании проекта, они будут перезаписаны настройками из загруженного conf.py.

Генерация html

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

make html

Если сборка выполнена успешно, каталог _build/html содержит html-файлы:

html
│   .buildinfo
│   easter-egg.html
│   genindex.html
│   index.html
│   objects.inv
│   search.html
│   searchindex.js
│
├───_images
├───_sources
└───_static

Если вы откроете index.html в браузере, вы должны увидеть демонстрационный проект:

The Zen of Python