Package: tinydocs
TinydocsLightweight autodoc for github.Are you in need of a simple and efficient solution for documenting your Python code, without the hassle of setting up and maintaining a full-fledged documentation website likereadthedocs? Do you want something that can quickly and easily be integrated into GitHub, allowing your team to quickly access the documentation for a few classes and helper functions? Look no further!Tinydocs is right for you!readthedocsautomatically generates the documentation of your.pyfiles in a small elegant way that fits in a simpleREADME.md. Check out the example function below or theexample directory.ContentsInstallationExampleSyntaxBasic UsageGithub WorkflowInstallationBest way to install tinydocs is through pip:pipinstalltinydocsExampleThe following is an example of the documentation egenrated for a simple function. YOu can finde howtinydocshandles and entire directory by checking theexample directory.Functionmodule.function(var1,var2,long_var_name=None,*args)WarningDeprecation:functionwill be removed in version 2.0.0, it is replaced bybetter_functionbecause the new one is blazingly fast.This is an example documentation.
Several sentences providing an extended description. Refer to
variables using back-ticks, e.g.var.
Look at this really big equation that I took from [^1]$$( \sum_{k=1}^n a_k b_k )^2 \leq ( \sum_{k=1}^n a_k^2 ) ( \sum_{k=1}^n b_k^2 )$$Parametersvar1: array_likeArray_like means all those objects -- lists, nested lists, etc. --
that can be converted to an array.  We can also refer to
variables like `var1`.var2: intThe type above can either refer to an actual Python type
(e.g. ``int``), or describe the type of the variable in more
detail, e.g. ``(N,) ndarray`` or ``array_like``.long_var_name: {'hi', 'ho'}, optionalChoices in brackets, default first when optional.*args: iterableOther arguments.Returnsvar3: intReturns `var3` which is of type ``int``.ExamplesThese are written in doctest format, and should illustrate how to
use the function.>>>a=[1,2,3]>>>b=deprecated_function(a)>>>print(b)[4,5,6][^1]: Trager, Scott. "The Earth's atmosphere: seeing, background, absorption & scattering" (PDF). S.C. Trager. Retrieved 31 May 2022SyntaxCurrentlytinydocsonly supportsNumpyDocsyntax. This might change in the future. For a detailed guide check out numpy's style guidelines you can also check-out theexample directoryof this project.Here is the docstring that generates the documentation on the example above, taken mostly fromnumpydoc's example.deffunction(var1,var2,long_var_name=None,*args):"""This is an example documentation.Several sentences providing an extended description. Refer tovariables using back-ticks, e.g. `var`.Parameters----------var1 : array_likeArray_like means all those objects -- lists, nested lists, etc. --that can be converted to an array.  We can also refer tovariables like `var1`.var2 : intThe type above can either refer to an actual Python type(e.g. ``int``), or describe the type of the variable in moredetail, e.g. ``(N,) ndarray`` or ``array_like``.long_var_name : {'hi', 'ho'}, optionalChoices in brackets, default first when optional.*args : iterableOther arguments.Returns-------var3 : intReturns `var3` which is of type ``int``.Notes-----Look at this really big equation that I took from [1]_$$( \sum_{k=1}^n a_k b_k )^2 \leq ( \sum_{k=1}^n a_k^2 ) ( \sum_{k=1}^n b_k^2 )$$Warnings--------Deprecation Warning: `deprecated_function` will be removed in version 2.0.0, it is replaced by `better_function` because the new one is blazingly fast.References----------.. [1] Trager, Scott. "The Earth's atmosphere: seeing, background, absorption & scattering" (PDF). S.C. Trager. Retrieved 31 May 2022Examples--------These are written in doctest format, and should illustrate how touse the function.>>> a = [1, 2, 3]>>> b = deprecated_function(a)>>> print(b)[4,5,6]"""passBasic Usagetinydocscan be run directly from the command line using:tinydocs<options>NoteBy design--tinydocsonly looks at.pyfiles and skips over hidden directories or files/functions/methods that start with "_"(underscore).--dir: Directory to document. Defaults to working directory.--output: Output path and name of documentation file. Defaults to--dir/TINYDOCS.mdwhen not supplied.--exclude-dirs: List of directories to exclude entirely from the documentation.--exclude-files: List of files to exclude individually from the documentation.--help: Help will always be given to those who ask for it.Github Workflowtinydocsincorporates very well with automatic deployment allowing you to update your documentation on every push. Here's an example workflow on.github/workflows/tinydocs.yaml:name:Update TINYDOCS.mdon:push:branches:-"*"jobs:build:runs-on:ubuntu-lateststeps:-name:Checkout codeuses:actions/checkout@v2-name:Setup Pythonuses:actions/setup-python@v2with:python-version:3.10-name:Install tinydocsrun:pip install tinydocs-name:Run tinydocsrun:tinydocs-name:Commit and push TINYDOCS.mdrun:|git config --local user.email "github-actions@example.com"git config --local user.name "GitHub Actions"git add TINYDOCS.mdgit commit -m "Update TINYDOCS.md"git push