Помогите начать работать с sphinx. Нужно вывести в справку API функций некоторого хорошо задокументированного пакета.
Пусть у нас имеется пакет mypack1 и модуль mylib, содержащий задокументированные функции
$ cat mylib.py
#!/usr/bin/python3
import numpy as np
def fun1(x):
""" Return sum of squares.
Parametrs:
----------
x: numpy.ndarray
Argument of function.
Examples:
--------
a = np.array([1,2,3])
b = fun1(x=a)
"""
return np.sum(x**2)
...
Командами sphinx-quickstart и make html была сгенерирована документация, но API там не появилась автоматом. Как можно делать API автоматически, по комментариям к функциям - не перенабирая и не копируя код заново?
$ tree
.
├── docs
│ ├── build
│ │ ├── doctrees
...
│ ├── Makefile
│ └── source
│ ├── conf.py
│ ├── index.rst
│ ├── _static
│ └── _templates
└── mypack1
└── mylib.py
$ cat conf.py | egrep -vE "(^#|^$)"
import sys
import os
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.mathjax',
'sphinx.ext.ifconfig',
'sphinx.ext.viewcode',
]
templates_path = ['_templates']
source_suffix = '.rst'
master_doc = 'index'
project = u'MyProject'
copyright = u'2018, MyName'
author = u'MyName'
version = u'1'
release = u'1.0'
language = None
exclude_patterns = []
pygments_style = 'sphinx'
todo_include_todos = True
html_theme = 'alabaster'
html_static_path = ['_static']
htmlhelp_basename = 'MyProjectdoc'
latex_elements = {
}
latex_documents = [
(master_doc, 'MyProject.tex', u'MyProject Documentation',
u'MyName', 'manual'),
]
man_pages = [
(master_doc, 'myproject', u'MyProject Documentation',
[author], 1)
]
texinfo_documents = [
(master_doc, 'MyProject', u'MyProject Documentation',
author, 'MyProject', 'One line description of project.',
'Miscellaneous'),
]
epub_title = project
epub_author = author
epub_publisher = author
epub_copyright = copyright
epub_exclude_files = ['search.html']
intersphinx_mapping = {'https://docs.python.org/': None}