https://github.com/anntzer/speedoc
sphinx meets pydoc
https://github.com/anntzer/speedoc
pydoc sphinx-doc
Last synced: 5 months ago
JSON representation
sphinx meets pydoc
- Host: GitHub
- URL: https://github.com/anntzer/speedoc
- Owner: anntzer
- License: mit
- Created: 2017-11-08T06:52:42.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2024-09-06T17:36:06.000Z (almost 2 years ago)
- Last Synced: 2025-02-27T23:29:26.324Z (over 1 year ago)
- Topics: pydoc, sphinx-doc
- Language: Python
- Size: 44.9 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGELOG.rst
- License: LICENSE.txt
Awesome Lists containing this project
README
speedoc – sphinx meets pydoc
============================
|PyPI|
.. |PyPI| image:: https://img.shields.io/pypi/v/speedoc.svg
:target: https://pypi.python.org/pypi/speedoc
Turn docstrings into man pages using Sphinx_, and view the result with ``man``.
.. _Sphinx: http://www.sphinx-doc.org
Installation
------------
.. code:: sh
python -mpip install git+https://github.com/anntzer/speedoc
Tests can be run with pytest_.
.. _pytest: https://docs.pytest.org
Usage
-----
.. code:: sh
speedoc [--opts ...] obj.to.document
Options are passed as is to ``python -msphinx``. By default, ``sphinx`` is
invoked as
.. code:: sh
# $tmpdir1, $tmpdir2 are set up by speedoc.
# -bman: build a man page; -q: quietly
python -msphinx $tmpdir1 $tmpdir2 -bman -q -Dextensions=sphinx.ext.napoleon
with a minimal ``conf.py`` that sets ``man_pages = [("contents", obj_name,
"\n", "", "3")]``. To use, e.g., numpydoc_ instead of sphinx.ext.napoleon_,
call
.. code:: sh
speedoc -Dextensions=sphinx.ext.autodoc,numpydoc obj.to.document
(With numpydoc≥0.9, it is not necessary anymore to explicitly load autodoc.)
Options to ``man`` can be passed by setting the (standard) ``MANOPT``
environment variable. For example, justification can be disabled with
.. code:: sh
MANOPT=--nj speedoc ...
.. _numpydoc: https://numpydoc.readthedocs.io
.. _sphinx.ext.autosummary: http://www.sphinx-doc.org/ext/autosummary.html
.. _sphinx.ext.napoleon: http://www.sphinx-doc.org/ext/napoleon.html
Troubleshooting
---------------
:Q: Docstrings are rendered terribly!
:A: Invalid RST formatting is very common :-(