# PyMdDoc
Generate markdown documentation for your Python scripts' code comments that is compatible with GitHub. It's like Sphinx, but with simpler requirements and results. It's also not as flexible as Sphinx and is mainly useful for scripts containing only a few classes.
For example output, [see the code documentation for this module](https://github.com/subalterngames/py_md_doc/blob/main/docs/py_md_doc.md).
## Installation
```bash
pip3 install py-md-doc
```
## Usage
### 1. Documentation for this module
1. Clone this repo.
2. `cd path/to/py_md_doc` (Replace `path_to`) with the actual path to this repo.)
3. `python3 doc_gen.py`
### 2. Documentation for your own module
```python
from py_md_doc import PyMdDoc
from pathlib import Path
md = PyMdDoc(input_directory=Path("my_module/my_module"), files=["my_script.py"], metadata_path="metadata.json")
md.get_docs(output_directory=Path("my_module/docs"))
```
**For the API, [read this](https://github.com/subalterngames/py_md_doc/blob/main/docs/py_md_doc.md).**
### 3. Documentation with class inheritance
1. Generate documentation for each child script (see above).
2. Use [`ClassInheritance`](https://github.com/subalterngames/py_md_doc/blob/main/docs/class_inheritance.md) to append inherited fields, functions, etc. from the generated documents.
## Code comments format
- One class per file.
- Class descriptions begin and end with `"""` immediately after the class definition.
- Class variables begin with `""":class_var` and end with `"""` and must be before the constructor declaration. The line immediately after them is the variable declaration.
- Fields begin with `""":field` and end with `"""` in the constructor. The line immediately after them is the field declaration.
- Function descriptions begin and end with `"""` immediately after the function definition.
- Function parameter descriptions are lines within the function description that begin with `:param`
- Function return description are lines within the function description that begin with `:return:`
- Function names that begin with `_` are ignored.
- The code for PyMdDoc as well as the code examples below use [type hinting](https://docs.python.org/3/library/typing.html). You do _not_ need type hinting in your code for PyMdDoc to work properly.
```python
class MyClass:
"""
This is the class description.
"""
""":class_var
This is a class variable.
"""
CLASS_VAR: int = 0
def __init__(self):
"""field:
The ID of this object.
"""
self.val = 0
def set_val(self, val: int) -> None:
"""
Set the val of this object.
:param val: The new value.
"""
self.val = val
def get_val(self) -> int:
"""
:return The value of this object.
"""
return self.val
def _private_function(self) -> None:
"""
This won't appear in the documentation.
"""
return
```
- [Enum values](https://docs.python.org/3/library/enum.html) are documented by commenting the line next to them.
```python
from enum import Enum
class MyEnum(Enum):
a = 0 # The first value.
b = 1 # The second value.
```
## Metadata file
You can add an optional metadata dictionary (see [the constructor](https://github.com/subalterngames/py_md_doc/blob/main/docs/py_md_doc.md#__init__)).
A metadata file is structured like this:
```json
{
"PyMdDoc":
{
"Constructor": {
"description": "",
"functions": ["__init__"]
},
"Documentation Generation": {
"description": "Use these functions to generate your documentation.",
"functions": ["get_docs", "get_doc"]
},
"Helper Functions": {
"description": "These functions are used in `get_docs()`. You generally won't need to call these yourself.",
"functions": ["get_class_description", "get_class_variables", "get_function_documentation", "get_enum_values", "get_fields"]
}
}
}
```
- The top-order key of the dictionary (`"PyMdDoc"`) is the name of the class. You don't need to add every class that you wish to document. If the class is not listed in `metadata.json` but is listed in the `files` parameter, its functions will be documented in the order they appear in the script.
- Each key in the class metadata (`"Constructor"`, `"Documentation Generation"`, `"Helper Functions"`) is a section.
- Each section name will be a header in the document, except for `"Constructor"` and `"Ignore"`.
- Any function in the `"Ignore"` category won't be documented.
- Each section has a `"description"` and a list of names of `"functions"`. The functions will appear in the section in the order they appear in this list.
- If the class name is listed in `metadata.json` and a function name can't be found in any of the section lists, the console will output a warning. For example, if you were to add a function named `new_function()` to `PyMdDoc`, you'd have to add it to a section in the metadata file as well because `PyMdDoc` is a key in the metadata dictionary.
## Limitations
- This script is for class objects only and won't document functions that aren't in classes:
```python
def my_func():
"""
This function will be ignored.
"""
pass
class MyClass:
"""
This class will be in the documentation.
"""
def class_func(self):
"""
This function will be in the documentation.
"""
pass
def another_my_func():
"""
This function will be erroneously included with MyClass.
"""
pass
```
- Functions can be grouped and reordered into categories, but classes and fields are always documented from the top of the document to the bottom:
```python
class MyClass:
"""
This class will documented first.
"""
def class_func(self):
"""
This function will be documented first.
"""
pass
def another_class_func(self):
"""
This function will be documented second.
"""
pass
class AnotherClass:
"""
This class will be documented second.
"""
```
## `VarDoc`
To create API documentation for a script that contains only variables (no classes or functions), use [`VarDoc`](https://github.com/subalterngames/py_md_doc/blob/main/docs/var_doc.md).
# Changelog
See [changelog](docs/changelog.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/subalterngames/py_md_doc",
"name": "py-md-doc",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "documentation,doc,sphinx,markdown,github",
"author": "Seth Alter",
"author_email": "subalterngames@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d8/ef/3c5baf1466e17b373614b5017d6127616f48f7847ec8479529f601c7871b/py_md_doc-0.5.1.tar.gz",
"platform": null,
"description": "# PyMdDoc\r\n\r\nGenerate markdown documentation for your Python scripts' code comments that is compatible with GitHub. It's like Sphinx, but with simpler requirements and results. It's also not as flexible as Sphinx and is mainly useful for scripts containing only a few classes.\r\n\r\nFor example output, [see the code documentation for this module](https://github.com/subalterngames/py_md_doc/blob/main/docs/py_md_doc.md).\r\n\r\n## Installation\r\n\r\n```bash\r\npip3 install py-md-doc\r\n```\r\n\r\n## Usage\r\n\r\n\r\n### 1. Documentation for this module\r\n\r\n1. Clone this repo.\r\n2. `cd path/to/py_md_doc` (Replace `path_to`) with the actual path to this repo.)\r\n3. `python3 doc_gen.py`\r\n\r\n### 2. Documentation for your own module\r\n\r\n```python\r\nfrom py_md_doc import PyMdDoc\r\nfrom pathlib import Path\r\n\r\n\r\nmd = PyMdDoc(input_directory=Path(\"my_module/my_module\"), files=[\"my_script.py\"], metadata_path=\"metadata.json\")\r\nmd.get_docs(output_directory=Path(\"my_module/docs\"))\r\n```\r\n\r\n**For the API, [read this](https://github.com/subalterngames/py_md_doc/blob/main/docs/py_md_doc.md).**\r\n\r\n### 3. Documentation with class inheritance\r\n\r\n1. Generate documentation for each child script (see above).\r\n2. Use [`ClassInheritance`](https://github.com/subalterngames/py_md_doc/blob/main/docs/class_inheritance.md) to append inherited fields, functions, etc. from the generated documents.\r\n\r\n## Code comments format\r\n\r\n- One class per file.\r\n- Class descriptions begin and end with `\"\"\"` immediately after the class definition.\r\n- Class variables begin with `\"\"\":class_var` and end with `\"\"\"` and must be before the constructor declaration. The line immediately after them is the variable declaration.\r\n- Fields begin with `\"\"\":field` and end with `\"\"\"` in the constructor. The line immediately after them is the field declaration.\r\n- Function descriptions begin and end with `\"\"\"` immediately after the function definition.\r\n - Function parameter descriptions are lines within the function description that begin with `:param`\r\n - Function return description are lines within the function description that begin with `:return:`\r\n- Function names that begin with `_` are ignored.\r\n- The code for PyMdDoc as well as the code examples below use [type hinting](https://docs.python.org/3/library/typing.html). You do _not_ need type hinting in your code for PyMdDoc to work properly.\r\n\r\n```python\r\nclass MyClass:\r\n \"\"\"\r\n This is the class description.\r\n \"\"\"\r\n\r\n \"\"\":class_var\r\n This is a class variable.\r\n \"\"\"\r\n CLASS_VAR: int = 0\r\n\r\n def __init__(self):\r\n \"\"\"field:\r\n The ID of this object.\r\n \"\"\"\r\n self.val = 0\r\n\r\n def set_val(self, val: int) -> None:\r\n \"\"\"\r\n Set the val of this object.\r\n\r\n :param val: The new value.\r\n \"\"\"\r\n\r\n self.val = val\r\n\r\n def get_val(self) -> int:\r\n \"\"\"\r\n :return The value of this object.\r\n \"\"\"\r\n \r\n return self.val\r\n\r\n def _private_function(self) -> None:\r\n \"\"\"\r\n This won't appear in the documentation.\r\n \"\"\"\r\n\r\n return\r\n```\r\n\r\n- [Enum values](https://docs.python.org/3/library/enum.html) are documented by commenting the line next to them.\r\n\r\n```python\r\nfrom enum import Enum\r\n\r\nclass MyEnum(Enum):\r\n a = 0 # The first value.\r\n b = 1 # The second value.\r\n```\r\n\r\n## Metadata file\r\n\r\nYou can add an optional metadata dictionary (see [the constructor](https://github.com/subalterngames/py_md_doc/blob/main/docs/py_md_doc.md#__init__)).\r\n\r\nA metadata file is structured like this:\r\n\r\n```json\r\n{\r\n \"PyMdDoc\":\r\n {\r\n \"Constructor\": {\r\n \"description\": \"\",\r\n \"functions\": [\"__init__\"]\r\n },\r\n \"Documentation Generation\": {\r\n \"description\": \"Use these functions to generate your documentation.\",\r\n \"functions\": [\"get_docs\", \"get_doc\"]\r\n },\r\n \"Helper Functions\": {\r\n \"description\": \"These functions are used in `get_docs()`. You generally won't need to call these yourself.\",\r\n \"functions\": [\"get_class_description\", \"get_class_variables\", \"get_function_documentation\", \"get_enum_values\", \"get_fields\"]\r\n }\r\n }\r\n}\r\n```\r\n\r\n- The top-order key of the dictionary (`\"PyMdDoc\"`) is the name of the class. You don't need to add every class that you wish to document. If the class is not listed in `metadata.json` but is listed in the `files` parameter, its functions will be documented in the order they appear in the script.\r\n- Each key in the class metadata (`\"Constructor\"`, `\"Documentation Generation\"`, `\"Helper Functions\"`) is a section.\r\n - Each section name will be a header in the document, except for `\"Constructor\"` and `\"Ignore\"`.\r\n - Any function in the `\"Ignore\"` category won't be documented.\r\n - Each section has a `\"description\"` and a list of names of `\"functions\"`. The functions will appear in the section in the order they appear in this list.\r\n- If the class name is listed in `metadata.json` and a function name can't be found in any of the section lists, the console will output a warning. For example, if you were to add a function named `new_function()` to `PyMdDoc`, you'd have to add it to a section in the metadata file as well because `PyMdDoc` is a key in the metadata dictionary.\r\n\r\n## Limitations\r\n\r\n- This script is for class objects only and won't document functions that aren't in classes:\r\n\r\n```python\r\ndef my_func():\r\n \"\"\"\r\n This function will be ignored.\r\n \"\"\"\r\n pass \r\n\r\nclass MyClass:\r\n \"\"\"\r\n This class will be in the documentation.\r\n \"\"\"\r\n\r\n def class_func(self):\r\n \"\"\"\r\n This function will be in the documentation.\r\n \"\"\"\r\n pass\r\n\r\ndef another_my_func():\r\n \"\"\"\r\n This function will be erroneously included with MyClass.\r\n \"\"\"\r\n pass \r\n```\r\n\r\n- Functions can be grouped and reordered into categories, but classes and fields are always documented from the top of the document to the bottom:\r\n\r\n```python\r\nclass MyClass:\r\n \"\"\"\r\n This class will documented first.\r\n \"\"\"\r\n\r\n def class_func(self):\r\n \"\"\"\r\n This function will be documented first.\r\n \"\"\"\r\n pass\r\n\r\n def another_class_func(self):\r\n \"\"\"\r\n This function will be documented second.\r\n \"\"\"\r\n pass\r\n\r\nclass AnotherClass:\r\n \"\"\"\r\n This class will be documented second.\r\n \"\"\"\r\n```\r\n\r\n## `VarDoc`\r\n\r\nTo create API documentation for a script that contains only variables (no classes or functions), use [`VarDoc`](https://github.com/subalterngames/py_md_doc/blob/main/docs/var_doc.md).\r\n\r\n# Changelog\r\n\r\nSee [changelog](docs/changelog.md).\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate markdown documentation for your Python scripts.Like Sphinx, but simpler and directly compatible with GitHub.",
"version": "0.5.1",
"project_urls": {
"Download": "https://github.com/subalterngames/py_md_doc/archive/0.1.tar.gz",
"Homepage": "https://github.com/subalterngames/py_md_doc"
},
"split_keywords": [
"documentation",
"doc",
"sphinx",
"markdown",
"github"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d8ef3c5baf1466e17b373614b5017d6127616f48f7847ec8479529f601c7871b",
"md5": "e1311cdedcf5cd1155876c336b74d361",
"sha256": "2a6d0d7ede67f29f41f8a143d662677c355bcc6d7596078ab193e6468c7fda45"
},
"downloads": -1,
"filename": "py_md_doc-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "e1311cdedcf5cd1155876c336b74d361",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16092,
"upload_time": "2023-10-02T18:08:34",
"upload_time_iso_8601": "2023-10-02T18:08:34.278432Z",
"url": "https://files.pythonhosted.org/packages/d8/ef/3c5baf1466e17b373614b5017d6127616f48f7847ec8479529f601c7871b/py_md_doc-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-02 18:08:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "subalterngames",
"github_project": "py_md_doc",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "py-md-doc"
}
JSON
