Получить Sphinx в Pycharm, чтобы включить мои строки документации в сгенерированный HTML - PullRequest
Новая
       44

Получить Sphinx в Pycharm, чтобы включить мои строки документации в сгенерированный HTML

0 голосов
/ 19 февраля 2019

У меня есть проект Pycharm, использующий интерпретатор Python 3.7.2, и я настроил Sphinx для генерации документации.Мой проект имеет следующую структуру: 

/my_project/
  /docs/
  /src/
    /modules/
    /tools/

В модулях и инструментах есть модули python, которые были задокументированы с помощью строк документации.Я настроил Sphinx для создания документации в / docs, но эта документация имеет только базовый index.rst.Как я могу получить документацию по модулю python из моих строк документации, которая будет помещена в папку / docs?

1 Ответ

0 голосов
/ 19 февраля 2019

Может быть, вы могли бы попробовать следующее:

  1. Убедитесь, что у ваших модулей, которые вы пытаетесь документировать , есть файл __init__.py, чтобы вы могли импортировать их соответствующим образом позже,В вашем случае ваши каталоги tools и modules нуждаются в __init__.py файлах.
  2. Убедитесь, что все ваши модули, которые вы документируете, настроены с правильными sphinx аннотациями:

module_1.py: 

"""
.. module:: module_1
   :platform: Unix, Windows
   :synopsis: A useful module indeed.
"""

def public_fn_with_sphinxy_docstring(name, state=None):
    """This function does something.

    :param name: The name to use.
    :type name: str.
    :param state: Current state to be in.
    :type state: bool.
    :returns:  int -- the return code.
    :raises: AttributeError, KeyError

    """
    return 0
Создайте новый файл .rst, возможно, с именем code.rst, который включает в себя модули, которые вы хотите задокументировать.Затем укажите этот новый файл .rst в вашем index.rst:

code.rst: 

Documentation for the Code
**************************

.. automodule:: an_example_pypi_project


module #1 -- auto members
=========================

This is something I want to say that is not in the docstring.

.. automodule:: an_example_pypi_project.module_1
   :members:

index.rst: 

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

   # other rst files you're including in your sphinx docs

   code.rst

Вот действительно хорошее объяснение и учебник , если вы тоже хотите это проверить.Надеюсь, это поможет!

...