Automated Python Module Documentation in Markdown File (README)
Project description
Automated (Python) Module Documentation in README
What's this?
Automated docstring extraction and creation/update of documentation (of python modules) in README File.
Why?
Because it's nice :-)
How?
doc_to_md.py loops through all Python files in the Repository and extracts the function calls + the corresponding short description from the docstrings. These are added to a dictionary and afterwards converted to a Markdown Table. Finally, the section Functions & Classes is appended / updated in the README File.
There are several options how to use it:
a) Python Package
b) CI Pipeline
a) install & use Python Package
Available on PyPI
pip install doc-to-readme
- Use within Python
import doc_to_md.doc_to_md as dtm
dtm.update_markdown_file(
file="README.md",
root_dir=None, # Directory used as root for searching modules, defaults to folder containing README.md
exclude_modules=None, # List of modules to be excluded
specified_modules=None, # Only these modules will be included
separate=True # Create one table per module
)
- Command Line
python -m doc_to_md.doc_to_md -f "README.md" [-r ROOT_DIR] [-e EXCLUDE_MODULES] [-m SELECTED_MODULES] [--separated]
-r ROOT_DIR # Directory used as root for searching modules, defaults to folder containing README.md
-e EXCLUDE_MODULES # List of modules to be excluded
-m SELECTED_MODULES # Only these modules will be included
--separated # Create one table per module
b) add to Pipeline (GitHub, GitLab or Bitbucket)
Documentation on how to set up the pipelines to update a file on every push.
Step-by-step guide on how to integrate doc_to_readme in your Repository
Copyright © 2023 by Mirjam Ziselsberger
This code is free to use under the terms of the MIT license.
Functions & Classes
doc_to_md.py
Type | Name/Call | Description |
---|---|---|
function | loop_through_repo(file: str, root_dir: str = None, exclude_modules: Optional[Tuple[str, ...]] = None, specified_modules: Optional[Tuple[str, ...]] = None) -> None |
Collect documentation from functions & classes. |
function | add_summary_to_md(overview_dict: Dict[str, Optional[Union[str, Dict[str, str]]]], markdown: str, separate: bool = True) |
Add Table with all Functions & Classes to Markdown file. |
function | update_markdown_file(file: str = "../../README.md", root_dir: str = None, exclude_modules: Optional[Tuple[str, ...]] = ("test", "functions_for_testing", "classes_for_testing", "doc_to_md"), specified_modules: Optional[Tuple[str, ...]] = None, separate: bool = True) |
Add/update 'Functions & Classes' Section in Markdown file. |
function | parse_through_file(file: str) -> Dict[str, Dict[str, str]] |
Parse through file, return dict with classes and functions. |
Created with: doc_to_readme
MIT © 2023 Mirjam Ziselsberger
Last Update: 2023-05-03
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for doc_to_readme-1.1.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c7aae9aebcf3994cd0f7e58915ae184c019de5c0616af705a3532f0723e0f72b |
|
MD5 | 4b91f6294a53bc784d479bcec79a37ad |
|
BLAKE2b-256 | 35b008b3a11d5c250931f91cc483289abf0100e7d514e34621dea3cc1e08bb9e |