Создать проект можно ответив на вопросы через sphinx-quickstart или использовать уже подготовленный шаблон который генерит дополнительно API пакета:
sphinx-apidoc -F -o docs sacrud Creating file docs/sacrud_deform.rst. Creating file docs/sacrud_deform.tests.rst. Creating file docs/conf.py. Creating file docs/index.rst. Creating file docs/Makefile. Creating file docs/make.bat.
Автогенератор API обычно создает много лишнего и далеко не идеально генерит названия, поэтому удалим API тестов и попереимеуем все остальное.
Для сборки доков нужно в папке docs выполнить make html. Ниже структура получившихся файлов:
. ├── _build │ ├── doctrees │ │ ├── environment.pickle │ │ ├── index.doctree │ │ ├── readme.doctree │ │ ├── sacrud_deform.doctree │ │ └── sacrud_deform.tests.doctree │ └── html │ ├── genindex.html │ ├── index.html │ ├── _modules │ │ ├── index.html │ │ ├── sacrud_deform │ │ │ ├── tests │ │ │ │ └── test_form.html │ │ │ └── widgets.html │ │ └── sacrud_deform.html │ ├── objects.inv │ ├── py-modindex.html │ ├── readme.html │ ├── sacrud_deform.html │ ├── sacrud_deform.tests.html │ ├── search.html │ ├── searchindex.js │ ├── _sources │ │ ├── index.txt │ │ ├── readme.txt │ │ ├── sacrud_deform.tests.txt │ │ └── sacrud_deform.txt │ └── _static │ ├── ajax-loader.gif │ ├── basic.css │ ├── comment-bright.png │ ├── comment-close.png │ ├── comment.png │ ├── default.css │ ├── doctools.js │ ├── down.png │ ├── down-pressed.png │ ├── file.png │ ├── jquery.js │ ├── minus.png │ ├── plus.png │ ├── pygments.css │ ├── searchtools.js │ ├── sidebar.js │ ├── underscore.js │ ├── up.png │ ├── up-pressed.png │ └── websupport.js ├── conf.py ├── index.rst ├── make.bat ├── Makefile ├── readme.rst ├── sacrud_deform.rst ├── _static └── _templates
В директории build/html находится наша готовая документация в формате html. Добавим описание проекта на основную страницу. Для этого создаем readme.rst в директории docs и включаем его в index.rst, а в дальнейшем этот же readme.rst будет использоваться в README.rst в корне проекта для github и PyPi.
readme.rst
|Build Status| |Coverage Status| |Stories in Progress| |PyPI| .. |Build Status| image:: https://travis-ci.org/ITCase/sacrud_deform.svg?branch=master :target: https://travis-ci.org/ITCase/sacrud_deform .. |Coverage Status| image:: https://coveralls.io/repos/ITCase/sacrud_deform/badge.png?branch=master :target: https://coveralls.io/r/ITCase/sacrud_deform?branch=master .. |Stories in Progress| image:: https://badge.waffle.io/ITCase/sacrud_deform.png?label=in%20progress&title=In%20Progress :target: http://waffle.io/ITCase/sacrud_defrom .. |PyPI| image:: http://img.shields.io/pypi/dm/sacrud_deform.svg :target: https://pypi.python.org/pypi/sacrud_deform/ sacrud_deform ============== Form generotor for SQLAlchemy models. Install ======= develop version from source .. code-block:: bash pip install git+git://github.com/ITCase/sacrud_deform@develop from pypi .. code-block:: bash pip install sacrud_deform Use === .. code-block:: python data = form_generator(dbsession=DBSession, obj=obj_of_model, table=MyModel, columns=columns_of_model) form, js_list = data.render()
Здесь вроде все понятно, но есть нюансы, если например в директиве .. code-block не указать язык или не дописывать "=" в заголовках то документация будет нормально генериться, но PyPi её не поймет и выведет что-то типа этого:
Нужно быть внимательным и проверять как PyPi подхватил README.rst. Дальше в наш index.rst добавим readme.rst что бы он был по презентабельнее.
index.rst
Welcome to sacrud_deform's documentation! ========================================= .. include:: readme.rst Contents: .. toctree:: :maxdepth: 4 sacrud_deform Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`Теперь главная страница документации выглядит так:
В принципе уже хорошо, добавим это описание ещё для github и PyPi. Они по умолчанию берут файл README.rst из корня проекта и ничего про папку docs не знают. Можно было бы заинклудить readme.rst в корневой README.rst(..include:: docs/readme.rst), но github и PyPi инклуды не понимают, поэтому придется писать свой велосипед для копирования. Либо тупо делать это вручную. Я написал на коленке простой скрипт который это делает и заменяет директивы include содержанием их файлов.
make_README.py
import fileinput import os from shutil import copyfile src = "readme.rst" src_path = os.path.dirname(os.path.realpath(src)) dst = "../README.rst" copyfile(src, dst) def read_file(path): with open(path, 'r') as f: return f.read() for line in fileinput.input(dst, inplace=1): splitted = line.rstrip().split('.. include:: ') if len(splitted) == 2: line = read_file(os.path.join(src_path, splitted[1])) print line else: print line.rstrip()
Теперь если запустить из папки docs команду python make_README.py, то в корне проекта появится или перезапишется файл README.rst
Что бы это делалось автоматически при каждой сборке документации добавим в Makefile:
... readme: python make_README.py readme_html: html readme
При вызове "make readme_html" у нас будет собираться документация html и копипаститься readme.
Конфиг для sphinx лежит в папке документации с названием conf.py. В нем можно настраивать документацию как угодно, к примеру оформим тему как у проекта Pyramid.
Добавим в conf.py
import sys import os # Add and use Pylons theme if 'sphinx-build' in ' '.join(sys.argv): # protect against dumb importers from subprocess import call, Popen, PIPE p = Popen('which git', shell=True, stdout=PIPE) git = p.stdout.read().strip() cwd = os.getcwd() _themes = os.path.join(cwd, '_themes') if not os.path.isdir(_themes): call([git, 'clone', 'git://github.com/Pylons/pylons_sphinx_theme.git', '_themes']) else: os.chdir(_themes) call([git, 'checkout', 'master']) call([git, 'pull']) os.chdir(cwd) sys.path.append(os.path.abspath('_themes')) parent = os.path.dirname(os.path.dirname(__file__)) sys.path.append(os.path.abspath(parent)) wd = os.getcwd() os.chdir(parent) os.chdir(wd) for item in os.listdir(parent): if item.endswith('.egg'): sys.path.append(os.path.join(parent, item))
Этот код я скопировал из проекта Pyramid, он просто выкачивает их тему с github в директорию _themes. Далее укажем в конфиге название темы и где их искать.
# -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. html_theme = 'pyramid' # Add any paths that contain custom themes here, relative to this directory. html_theme_path = ['_themes']
После сборки проект будет выглядеть так:
Вообщем конфиг умеет много чего, есть еще много разных расширений, можно писать свои, либо переопределять/добавлять директивы итд. Вот например как вставлять ссылки на сторонние проекты:
# Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions += [ 'sphinx.ext.intersphinx' ] intersphinx_mapping = { 'sacrud': ('http://sacrud.readthedocs.org/en/latest/', None), }
Теперь можно писать так:
Use :py:class:`sacrud.common.TableProperty` decorator.
И наверно последний этап это добавление документации на readthedocs. Сложностей там особо нету, регаешься, добавляешь гитхаб профиль, синхронизируешь репы и выбираешь нужные. Хук на коммиты в таком случае вешается автоматически, единственное что нужно отметить что если в документации используется automodule нужно ставить галку virtualenv(в настройках readthedocs) иначе он просто будет пустым.
Готовый пример можно посмотреть здесь http://sacrud-deform.readthedocs.org/en/develop/
Комментариев нет:
Отправить комментарий