Включение внешней документации в проект Sphinx - PullRequest
Новая
       12

Включение внешней документации в проект Sphinx

6 голосов
/ 20 мая 2011

Мы поддерживаем довольно большую документацию, используя Sphinx в SVN.

В качестве части сгенерированного вывода мы хотели бы включить примечания к выпуску связанных модулей Python в качестве основного содержимого (а не гиперссылки!)Примечания к выпуску внешних модулей также поддерживаются в SVN.Есть ли какой-нибудь способ Sphinx-ih для извлечения частей документации из других (SVN) источников?Хорошо, использование внешних SVN - это способ решения проблемы, но, возможно, не самый умный способ ... какие-нибудь лучшие варианты?

1 Ответ

8 голосов
/ 25 мая 2011

Я могу придумать два варианта:

  1. Добавить ссылку svn:externals в удаленный проект (о котором вы уже знаете).
  2. Расширение Sphinx с помощью специальной директивы для включения файлов из удаленных хранилищ Subversion.

Я не эксперт по внутренним компонентам Sphinx, но смог собрать быстрое расширение, которое встраивает файлы из удаленного хранилища Subversion.

Расширение добавляет директиву svninclude, которая принимает 1 аргумент - URL-адрес хранилища, в котором находятся ваши документы. Он проверяет этот репозиторий во временном каталоге _svncache, расположенном в корне проекта, и затем читает содержимое каждого файла и вставляет его в конечный автомат синтаксического анализатора.

Вот код для расширения svninclude.py. Это упрощено и не имеет проверки ошибок в данный момент. Если вы планируете реализовать это, дайте мне знать, и я могу дать несколько дополнительных советов, если вы застряли: 

import os, re, subprocess, sys
from docutils import nodes, statemachine
from docutils.parsers.rst import directives
from sphinx.util.compat import Directive, directive_dwim

class SvnInclude(Directive):

    has_content = True
    required_arguments = 1
    optional_arguments = 0
    final_argument_whitespace = False

    def _setup_repo(self, repo):
        env = self.state.document.settings.env
        path = os.path.normpath(env.doc2path(env.docname, base=None))
        cache = os.path.join(os.path.dirname(path), '_svncache')
        root = os.path.join(cache, re.sub('[\W\-]+', '_', repo))
        if not os.path.exists(root):
            os.makedirs(root)
        subprocess.call(['svn', 'co', repo, root])
        return root

    def run(self):
        root = self._setup_repo(self.arguments[0])
        for path in self.content:
            data = open(os.path.join(root, path), 'rb').read()
            lines = statemachine.string2lines(data)
            self.state_machine.insert_input(lines, path)
        return []

def setup(app):
    app.add_directive('svninclude', directive_dwim(SvnInclude))

Вот пример разметки, которую вы включили бы в index.rst (или другой файл): 

.. svninclude:: http://svn.domain.com/svn/project

    one.rst
    doc/two.rst

Где пути one.rst и doc/two.rst относятся к URL подрывной деятельности, например http://svn.domain.com/svn/project/one.rst.

Вы, конечно, захотите упаковать svninclude.py и установить его в путь Python. Вот что я сделал, чтобы проверить это:

  1. Добавлен 'svninclude' в список extensions в source/conf.py.
  2. Помещено svninclude.py в корень проекта.

Затем побежал: 

% PYTHONPATH=. sphinx-build -b html ./source ./build
...