sphinxter
=========
Autodoc converting YAML docstrings and code comments to sphinx documentation
Formatting
----------
I wanted something that generated readable HTML documentation from readable Code documentation.
Even if you've done nothing to your code to use sphinxter, it'll generate decent documentation assuming non YAML
docstrings are descriptions for their resources.
Say this is yourmodule
```python
"""
The module description
"""
foo = None # The foo description
def func(
bar:int # The bar description
)->bool:
"""
The function description
"""
```
This would be the result in `docs/source/index.rst`:
```rst
.. created by sphinxter
.. default-domain:: py
yourmodule
==========
.. module:: yourmodule
The module description
.. attribute:: foo
The foo description
.. function:: func(bar: int)
The function description
:param bar: The bar description
:type bar: int
:rtype: bool
```
Not only is this decent documentation, sphinxter picked up the comments next to both attributes and function parameters,
which is a very common, readable pattern in code.
Another useful couple of features is that sphinxter can read dosctrings as YAML and it can read attributes docstrings
(which yes, don't really exist, but it works anyway) allowing for some complex but still readable behavior.
Say this is yourmodule now:
```python
"""
The module description
"""
foo = None # The foo description
"""
usage: |
Do it this way::
yourmodule.foo = 7
"""
def func(
bar:int # The bar description
)->bool:
"""
description: The function description
return: Whether the function worked or not
"""
```
This would now be the result in `docs/source/index.rst`:
```rst
.. created by sphinxter
.. default-domain:: py
yourmodule
==========
.. module:: yourmodule
The module description
.. attribute:: foo
The foo description
**Usage**
Do it this way::
yourmodule.foo = 7
.. function:: func(bar: int)
The function description
:param bar: The bar description
:type bar: int
:return: Whether the function worked or not
:rtype: bool
```
Taking advantage of attribute docstrings and YAML docstrings added more documentation, but didn't really lessen
the readability of the code.
That's the goal of sphinxter.
Organization
------------
By default, everything ends up in the `index.rst` document. With modules, classes, and functions you can a different
document and even the order in which they'll appear in the document. If the parent modules don't match, sphinxter will
add a currentmodule directive so everything will be organized properly.
Setup
-----
To setup a package to use sphinxter:
1. Install sphinxter (which includes sphinx)
```
pip install sphinxter
```
2. Setup documentation area as `docs/source`:
```
sphinx-quickstart docs --sep -p yourmodule -a 'Your Name' -r yourversion -l en
```
3. Create a script `docs.py` like so:
```
#!/usr/bin/env python
import sphinxter
import yourmodule
sphinxter.Sphinxter(yourmodule).process()
```
4. Run that script to auto generate docs from your docstrings (they'll end up in `docs/source`):
```
chmod a+x docs.py
./docs.py
```
5. Create HTML from those documents (they'll end up in `docs/build/html`):
```
sphinx-build -b html docs/source/ docs/build/html
```
Raw data
{
"_id": null,
"home_page": "https://sphinxter.readthedocs.io/en/0.1.7/",
"name": "sphinxter",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Gaffer Fitch",
"author_email": "sphinxter@gaf3.com",
"download_url": "https://files.pythonhosted.org/packages/86/0f/f0878a11e2c2b138fcf94e943f3660247bb21347305368e33b5881f3f1cd/sphinxter-0.1.7.tar.gz",
"platform": null,
"description": "sphinxter\n=========\n\nAutodoc converting YAML docstrings and code comments to sphinx documentation\n\nFormatting\n----------\n\nI wanted something that generated readable HTML documentation from readable Code documentation.\n\nEven if you've done nothing to your code to use sphinxter, it'll generate decent documentation assuming non YAML\ndocstrings are descriptions for their resources.\n\nSay this is yourmodule\n\n```python\n\"\"\"\nThe module description\n\"\"\"\n\nfoo = None # The foo description\n\ndef func(\n bar:int # The bar description\n)->bool:\n \"\"\"\n The function description\n \"\"\"\n```\n\nThis would be the result in `docs/source/index.rst`:\n\n```rst\n.. created by sphinxter\n.. default-domain:: py\n\nyourmodule\n==========\n\n.. module:: yourmodule\n\nThe module description\n\n.. attribute:: foo\n\n The foo description\n\n.. function:: func(bar: int)\n\n The function description\n\n :param bar: The bar description\n :type bar: int\n :rtype: bool\n```\n\nNot only is this decent documentation, sphinxter picked up the comments next to both attributes and function parameters,\nwhich is a very common, readable pattern in code.\n\nAnother useful couple of features is that sphinxter can read dosctrings as YAML and it can read attributes docstrings\n(which yes, don't really exist, but it works anyway) allowing for some complex but still readable behavior.\n\nSay this is yourmodule now:\n\n```python\n\"\"\"\nThe module description\n\"\"\"\n\nfoo = None # The foo description\n\"\"\"\nusage: |\n Do it this way::\n\n yourmodule.foo = 7\n\"\"\"\n\ndef func(\n bar:int # The bar description\n)->bool:\n \"\"\"\n description: The function description\n return: Whether the function worked or not\n \"\"\"\n```\n\nThis would now be the result in `docs/source/index.rst`:\n\n```rst\n.. created by sphinxter\n.. default-domain:: py\n\nyourmodule\n==========\n\n.. module:: yourmodule\n\nThe module description\n\n.. attribute:: foo\n\n The foo description\n\n **Usage**\n\n Do it this way::\n\n yourmodule.foo = 7\n\n.. function:: func(bar: int)\n\n The function description\n\n :param bar: The bar description\n :type bar: int\n :return: Whether the function worked or not\n :rtype: bool\n```\n\nTaking advantage of attribute docstrings and YAML docstrings added more documentation, but didn't really lessen\nthe readability of the code.\n\nThat's the goal of sphinxter.\n\nOrganization\n------------\n\nBy default, everything ends up in the `index.rst` document. With modules, classes, and functions you can a different\ndocument and even the order in which they'll appear in the document. If the parent modules don't match, sphinxter will\nadd a currentmodule directive so everything will be organized properly.\n\nSetup\n-----\n\nTo setup a package to use sphinxter:\n\n1. Install sphinxter (which includes sphinx)\n\n```\n pip install sphinxter\n```\n\n2. Setup documentation area as `docs/source`:\n\n```\n sphinx-quickstart docs --sep -p yourmodule -a 'Your Name' -r yourversion -l en\n```\n\n3. Create a script `docs.py` like so:\n\n```\n #!/usr/bin/env python\n\n import sphinxter\n import yourmodule\n\n sphinxter.Sphinxter(yourmodule).process()\n```\n\n4. Run that script to auto generate docs from your docstrings (they'll end up in `docs/source`):\n\n```\n chmod a+x docs.py\n ./docs.py\n```\n\n5. Create HTML from those documents (they'll end up in `docs/build/html`):\n\n```\n sphinx-build -b html docs/source/ docs/build/html\n```\n",
"bugtrack_url": null,
"license": "",
"summary": "Autodoc converting YAML docstrings and code comments to sphinx documentation",
"version": "0.1.7",
"project_urls": {
"Download": "https://github.com/gaf3/sphinxter",
"Homepage": "https://sphinxter.readthedocs.io/en/0.1.7/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a4addb06d529c0873f13b2726ed25aa9a62ba9db077ddfc7a578b534eadd3070",
"md5": "60ed59a094c61ef1432c9558865bab9e",
"sha256": "297205e6638fc8f40753ab6449efb888aa5a4af16aff68f551d6356d3c97ff55"
},
"downloads": -1,
"filename": "sphinxter-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "60ed59a094c61ef1432c9558865bab9e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 25504,
"upload_time": "2023-12-13T19:00:26",
"upload_time_iso_8601": "2023-12-13T19:00:26.551761Z",
"url": "https://files.pythonhosted.org/packages/a4/ad/db06d529c0873f13b2726ed25aa9a62ba9db077ddfc7a578b534eadd3070/sphinxter-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "860ff0878a11e2c2b138fcf94e943f3660247bb21347305368e33b5881f3f1cd",
"md5": "a99afc83ee0523e380482cc823191109",
"sha256": "19a56a4dee9d92af89a255edda213373411a5719781198f4400e78e029c5efbc"
},
"downloads": -1,
"filename": "sphinxter-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "a99afc83ee0523e380482cc823191109",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 24716,
"upload_time": "2023-12-13T19:00:28",
"upload_time_iso_8601": "2023-12-13T19:00:28.025192Z",
"url": "https://files.pythonhosted.org/packages/86/0f/f0878a11e2c2b138fcf94e943f3660247bb21347305368e33b5881f3f1cd/sphinxter-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-13 19:00:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gaf3",
"github_project": "sphinxter",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "sphinxter"
}
JSON
