{"id":20883919,"url":"https://github.com/antonio-leitao/tinydocs","last_synced_at":"2025-05-12T18:31:19.273Z","repository":{"id":65531399,"uuid":"593277705","full_name":"antonio-leitao/tinydocs","owner":"antonio-leitao","description":"TinyDocs is a lightweight and efficient solution for documenting Python code on Github, without the need for setting up and maintaining a separate website like readthedocs.","archived":false,"fork":false,"pushed_at":"2024-03-11T10:11:35.000Z","size":105,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-18T06:44:42.181Z","etag":null,"topics":["autodoc","documentation","github","python","readme"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/antonio-leitao.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2023-01-25T16:39:17.000Z","updated_at":"2023-10-04T08:38:24.000Z","dependencies_parsed_at":"2023-02-15T10:55:53.503Z","dependency_job_id":null,"html_url":"https://github.com/antonio-leitao/tinydocs","commit_stats":null,"previous_names":["antonio-leitao/docme"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antonio-leitao%2Ftinydocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antonio-leitao%2Ftinydocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antonio-leitao%2Ftinydocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antonio-leitao%2Ftinydocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/antonio-leitao","download_url":"https://codeload.github.com/antonio-leitao/tinydocs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253798027,"owners_count":21965991,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autodoc","documentation","github","python","readme"],"created_at":"2024-11-18T08:08:21.808Z","updated_at":"2025-05-12T18:31:19.009Z","avatar_url":"https://github.com/antonio-leitao.png","language":"Python","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src='assets/logo.svg' height='200px' align=\"center\"\u003e\u003c/img\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003ch3 max-width='200px' align=\"center\"\u003eTiny Docs\u003c/h3\u003e\n  \u003cp\u003e\u003ci\u003eLightweight autodoc for Python\u003cbr/\u003e\n  Creates an entire documentation into a single Markdown file\u003cbr/\u003e\n  Perfect for creating READMEs\u003c/i\u003e\u003cbr/\u003e\u003c/p\u003e\n  \u003cp\u003e\n\u003cimg alt=\"Pepy Total Downlods\" src=\"https://img.shields.io/pepy/dt/tinydocs?style=for-the-badge\u0026logo=python\u0026labelColor=white\u0026color=blue\"\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n#\n\nAre 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 like `readthedocs`? 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!\n\n\u003ch3 align=\"center\"\u003eTinydocs is right for you!\u003c/h3\u003e\n\n`readthedocs` automatically generates the documentation of your `.py` files in a small elegant way that fits in a simple `README.md`. Check out the example function below or the [example directory.](#https://github.com/antonio-leitao/tinydocs/tree/master/example)\n\n#### Contents\n\n- [Installation](#installation)\n- [Example](#example)\n- [Syntax](#syntax)\n- [Basic Usage](#basic_usage)\n- [Github Workflow](#github-workflow)\n\n# Installation\n\nBest way to install tinydocs is through pip:\n\n```sh\npip install tinydocs\n```\n\n# Example\n\nThe following is the documentation generated for an example function. You can find how `tinydocs` handles and entire directory by checking the [example directory](#https://github.com/antonio-leitao/tinydocs/tree/master/example).\n\n### Function\n\n```python\nmodule.function(var1, var2, long_var_name=None, *args)\n```\n\n\u003e **Warning** Deprecation: `function` will be removed in version 2.0.0, it is replaced by `better_function` because the new one is blazingly fast.\n\nThis is an example documentation.\nSeveral sentences providing an extended description. Refer to\nvariables using back-ticks, e.g. `var`.\nLook at this really big equation that I took from [^1]\n\n$$( \\sum_{k=1}^n a_k b_k )^2 \\leq ( \\sum_{k=1}^n a_k^2 ) ( \\sum_{k=1}^n b_k^2 )$$\n\n\u003cdetails closed\u003e\u003csummary\u003e\u0026emsp;\u003cb\u003eParameters\u003c/b\u003e\u003c/summary\u003e\u003cp/\u003e\u003cul\u003e\u003cli\u003e\u003ccode\u003evar1\u003c/code\u003e: array_like\u003cbr\u003e\u0026emsp;Array_like means all those objects -- lists, nested lists, etc. --\nthat can be converted to an array.  We can also refer to\nvariables like `var1`.\u003c/li\u003e\u003cli\u003e\u003ccode\u003evar2\u003c/code\u003e: int\u003cbr\u003e\u0026emsp;The type above can either refer to an actual Python type\n(e.g. ``int``), or describe the type of the variable in more\ndetail, e.g. ``(N,) ndarray`` or ``array_like``.\u003c/li\u003e\u003cli\u003e\u003ccode\u003elong_var_name\u003c/code\u003e: {'hi', 'ho'}, optional\u003cbr\u003e\u0026emsp;Choices in brackets, default first when optional.\u003c/li\u003e\u003cli\u003e\u003ccode\u003e*args\u003c/code\u003e: iterable\u003cbr\u003e\u0026emsp;Other arguments.\u003c/li\u003e\u003c/ul\u003e\u003c/details\u003e\u003cdetails closed\u003e\u003csummary\u003e\u0026emsp;\u003cb\u003eReturns\u003c/b\u003e\u003c/summary\u003e\u003cp/\u003e\u003cul\u003e\u003cli\u003e\u003ccode\u003evar3\u003c/code\u003e: int\u003cbr\u003e\u0026emsp;Returns `var3` which is of type ``int``.\u003c/li\u003e\u003c/ul\u003e\u003c/details\u003e\u003cdetails closed\u003e\u003csummary\u003e\u0026emsp;\u003cb\u003eExamples\u003c/b\u003e\u003c/summary\u003e\u003cp/\u003e\n\nThese are written in doctest format, and should illustrate how to\nuse the function.\n\n```python\n\u003e\u003e\u003e a = [1, 2, 3]\n\u003e\u003e\u003e b = deprecated_function(a)\n\u003e\u003e\u003e print(b)\n[4,5,6]\n```\n\n\u003c/details\u003e\n\n[^1]: Trager, Scott. \"The Earth's atmosphere: seeing, background, absorption \u0026 scattering\" (PDF). S.C. Trager. Retrieved 31 May 2022\n\n# Syntax\n\nCurrently `tinydocs` only supports [NumpyDoc](#https://numpydoc.readthedocs.io/en/latest/format.html) syntax. This might change in the future. For a detailed guide check out numpy's style guidelines you can also check-out the [example directory](#https://github.com/antonio-leitao/tinydocs/tree/master/example) of this project.\n\nHere is the docstring that generates the documentation on the example above, taken mostly from [numpydoc's example](#https://numpydoc.readthedocs.io/en/latest/example.html#example).\n\n```python\ndef function(var1, var2, long_var_name=None, *args):\n    \"\"\"This is an example documentation.\n\n    Several sentences providing an extended description. Refer to\n    variables using back-ticks, e.g. `var`.\n\n    Parameters\n    ----------\n    var1 : array_like\n        Array_like means all those objects -- lists, nested lists, etc. --\n        that can be converted to an array.  We can also refer to\n        variables like `var1`.\n    var2 : int\n        The type above can either refer to an actual Python type\n        (e.g. ``int``), or describe the type of the variable in more\n        detail, e.g. ``(N,) ndarray`` or ``array_like``.\n    long_var_name : {'hi', 'ho'}, optional\n        Choices in brackets, default first when optional.\n    *args : iterable\n        Other arguments.\n\n    Returns\n    -------\n    var3 : int\n        Returns `var3` which is of type ``int``.\n\n    Notes\n    -----\n    Look at this really big equation that I took from [1]_\n\n    $$( \\sum_{k=1}^n a_k b_k )^2 \\leq ( \\sum_{k=1}^n a_k^2 ) ( \\sum_{k=1}^n b_k^2 )$$\n\n    Warnings\n    --------\n    Deprecation Warning: `deprecated_function` will be removed in version 2.0.0, it is\n     replaced by `better_function` because the new one is blazingly fast.\n\n    References\n    ----------\n    .. [1] Trager, Scott. \"The Earth's atmosphere: seeing, background, absorption \u0026\n    scattering\" (PDF). S.C. Trager. Retrieved 31 May 2022\n\n    Examples\n    --------\n    These are written in doctest format, and should illustrate how to\n    use the function.\n\n    \u003e\u003e\u003e a = [1, 2, 3]\n    \u003e\u003e\u003e b = deprecated_function(a)\n    \u003e\u003e\u003e print(b)\n    [4,5,6]\n    \"\"\"\n    pass\n```\n\n# Basic Usage\n\n`tinydocs` can be run directly from the command line using:\n\n```sh\ntinydocs \u003coptions\u003e\n```\n\n\u003e **Note** By design `--tinydocs` only looks at `.py` files and skips over hidden directories and will ignore any opbject (files, functions or methods) that start with `_`(underscore).\n\n- `--dir`: Directory to document. Defaults to working directory.\n- `--output`: Output path and name of documentation file. Defaults to `--dir/TINYDOCS.md` when not supplied.\n- `--exclude-dirs`: List of directories to exclude entirely from the documentation.\n- `--exclude-files`: List of files to exclude individually from the documentation.\n- `--help`: Help will always be given to those who ask for it.\n\n# Github Workflow\n\n`tinydocs` incorporates very well with automatic deployment allowing you to update your documentation on every push. Here's an example workflow on\n`.github/workflows/tinydocs.yaml`:\n\n```yaml\nname: Update TINYDOCS.md\n\non:\n  push:\n    branches:\n      - \"*\"\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n\n    steps:\n      - name: Checkout code\n        uses: actions/checkout@v2\n\n      - name: Setup Python\n        uses: actions/setup-python@v2\n        with:\n          python-version: 3.10\n\n      - name: Install tinydocs\n        run: pip install tinydocs\n\n      - name: Run tinydocs\n        run: tinydocs\n\n      - name: Commit and push TINYDOCS.md\n        run: |\n          git config --local user.email \"github-actions@example.com\"\n          git config --local user.name \"GitHub Actions\"\n          git add TINYDOCS.md\n          git commit -m \"Update TINYDOCS.md\"\n          git push\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantonio-leitao%2Ftinydocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantonio-leitao%2Ftinydocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantonio-leitao%2Ftinydocs/lists"}