{"id":15057041,"url":"https://github.com/stablecaps/eyes3scribe","last_synced_at":"2026-01-18T08:03:26.253Z","repository":{"id":210622259,"uuid":"700620005","full_name":"stablecaps/eyes3scribe","owner":"stablecaps","description":"Automatically creates HTML documentation files for BASH/Shell source code using markdown \u0026 python mkdocs","archived":false,"fork":false,"pushed_at":"2025-01-30T23:13:18.000Z","size":32319,"stargazers_count":1,"open_issues_count":19,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-28T13:06:47.055Z","etag":null,"topics":["auto-documentation","automation","bash","documentation","documentation-tool","html","mark","markdown","markdown-to-html","mkdocs","pandoc","python3","rst","shell","shell-script","sphinx","static-site-generator","website-builder","website-generation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stablecaps.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-10-05T00:30:42.000Z","updated_at":"2024-02-05T01:04:43.000Z","dependencies_parsed_at":"2023-12-21T01:32:15.449Z","dependency_job_id":"5e319d59-fbe4-4d8d-ab67-20f3a0c33cef","html_url":"https://github.com/stablecaps/eyes3scribe","commit_stats":null,"previous_names":["stablecaps/bash-auto-documatix","stablecaps/bash-auto-doc","stablecaps/autographilliaz","stablecaps/eyes3scribe"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/stablecaps/eyes3scribe","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stablecaps%2Feyes3scribe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stablecaps%2Feyes3scribe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stablecaps%2Feyes3scribe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stablecaps%2Feyes3scribe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stablecaps","download_url":"https://codeload.github.com/stablecaps/eyes3scribe/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stablecaps%2Feyes3scribe/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28533764,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["auto-documentation","automation","bash","documentation","documentation-tool","html","mark","markdown","markdown-to-html","mkdocs","pandoc","python3","rst","shell","shell-script","sphinx","static-site-generator","website-builder","website-generation"],"created_at":"2024-09-24T22:01:14.442Z","updated_at":"2026-01-18T08:03:26.224Z","avatar_url":"https://github.com/stablecaps.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Eyes3Scribe\n\n\u003cdiv align=\"center\"\u003e\n\n\n![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/eyes3scribe)\n[![Style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026logoColor=white)](https://github.com/stablecaps/eyes3scribe/blob/master/.pre-commit-config.yaml)\n[![Semantic Versions](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--versions-e10079.svg)](https://github.com/stablecaps/eyes3scribe/releases)\n[![License](https://img.shields.io/github/license/stablecaps/eyes3scribe)](https://github.com/stablecaps/eyes3scribe/blob/master/LICENSE)\n[![DeepSource](https://app.deepsource.com/gh/stablecaps/eyes3scribe.svg/?label=active+issues\u0026show_trend=true\u0026token=JveipNb_ClaKjk0YBBKrG-32)](https://app.deepsource.com/gh/stablecaps/eyes3scribe/)\n[![DeepSource](https://app.deepsource.com/gh/stablecaps/eyes3scribe.svg/?label=resolved+issues\u0026show_trend=true\u0026token=JveipNb_ClaKjk0YBBKrG-32)](https://app.deepsource.com/gh/stablecaps/eyes3scribe/)\n![Coverage Report](assets/images/coverage.svg)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/stablecaps/eyes3scribe/total)\n[![Test eyes3scribe](https://github.com/stablecaps/eyes3scribe/actions/workflows/test-python-app.yml/badge.svg)](https://github.com/stablecaps/eyes3scribe/actions/workflows/test-python-app.yml)\n[![repo-stats](https://github.com/stablecaps/eyes3scribe/actions/workflows/github-repo-stats.yml/badge.svg)](https://github.com/stablecaps/eyes3scribe/actions/workflows/github-repo-stats.yml)\n![Stable Version](https://img.shields.io/pypi/v/eyes3scribe?label=stable)\n[![Build status](https://github.com/stablecaps/eyes3scribe/workflows/build/badge.svg?branch=master\u0026event=push)](https://github.com/stablecaps/eyes3scribe/actions?query=workflow%3Abuild)\n\n\nAutomatically creates HTML documentation files for BASH/Shell source code using markdown \u0026 python mkdocs\n\n\u003c/div\u003e\n\n# This is still a WIP!!!\n\n## Overview\nThis project is a Python application that uses pip for package management. The main entry point for the application is gen_mkdocs_site.py.\n\n**Features:**\n\n0. Uses mkdocs to create websites with any mkdocs theme\n1. Auto-generates BASH shell script documentation from src code that are marked with composure annotations.\n2. Create alias tables from shell code\n3. Preserves handwritten documentation (TBD)\n4. Converts existing RST docs --\u003e Markdown docs (TBD)\n5. Auto-generates Python documentation from source code (TBD)\n\n\n### Prerequisites\n* Python 3.x\n* poetry/pip\n\n## Installation\n\n```\ngit clone \u003crepository_url\u003e\ncd \u003cproject_directory\u003e\npython -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n```\n\n## Usage\n```\n# Run program to create mkdocs documentation site and serve it locally.\npython gen_mkdocs_site.py --site-confname config/bash_it_site.yaml ---build-serve\n\n# Show help\npython gen_mkdocs_site.py --help\n```\n### Program options\n1. `--site_confname` (str): The name of the site configuration.\n2. `--build_serve` (bool): Whether to build and serve the local MkDocs site.\n3. `--check_singlefile` (str): The path of a single shell source file to debug.\n4. `--debug` (bool, optional): If True, debug information will be printed. Defaults to False.\n\n\n\n## Program structure\n\n**Auto-Documatix Callgraph:**\n__(made with [PyDeps](https://github.com/thebjorn/pydeps?tab=readme-ov-file#usage))__\n![PyDeps](images/launcher.svg)\n\n## Contributing\nPlease read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.\n\n## License\nThis project is licensed under the Apache 2.0 License - see the LICENSE.md file for details.\n\n\n## Not so Random info links\n\n### Python call graphs\n1. [Generating and using a Callgraph, in Python](https://cerfacs.fr/coop/pycallgraph)\n2. [Quick \u0026 Simple Call Graphs in Python](https://medium.com/parkbee/quick-simple-call-graphs-in-python-eaa583d0e1b2)\n    [pyan](https://github.com/Technologicat/pyan)\n3. [Build a Call graph in python including modules and functions?](https://stackoverflow.com/questions/13963321/build-a-call-graph-in-python-including-modules-and-functions)\n4. [What is a Call Graph? And How to Generate them Automatically](https://www.freecodecamp.org/news/how-to-automate-call-graph-creation/)\n5. [Crabviz: a call graph generator for various programming languages](https://www.reddit.com/r/rust/comments/142is0h/crabviz_a_call_graph_generator_for_various/)\n6. [**Insane**: Callgraphs with Ghidra, Pyhidra, and Jpype](https://clearbluejar.github.io/posts/callgraphs-with-ghidra-pyhidra-and-jpype/)\n\n\n### Dependency analysis v2\n\n1. https://github.com/glato/emerge\n2. https://github.com/thebjorn/pydeps\n3. https://www.python.org/success-stories/building-a-dependency-graph-of-our-python-codebase/\n\n\n## Very first steps\n\n### Initialize your code\n\n1. Initialize `git` inside your repo:\n\n```bash\ncd eyes3scribe \u0026\u0026 git init\n```\n\n2. If you don't have `Poetry` installed run:\n\n```bash\nmake poetry-download\n```\n\n3. Initialize poetry and install `pre-commit` hooks:\n\n```bash\nmake install\nmake pre-commit-install\n```\n\n4. Run the codestyle:\n\n```bash\nmake codestyle\n```\n\n5. Upload initial code to GitHub:\n\n```bash\ngit add .\ngit commit -m \":tada: Initial commit\"\ngit branch -M main\ngit remote add origin https://github.com/stablecaps/eyes3scribe.git\ngit push -u origin main\n```\n\n### Set up bots\n\n- Set up [Dependabot](https://docs.github.com/en/github/administering-a-repository/enabling-and-disabling-version-updates#enabling-github-dependabot-version-updates) to ensure you have the latest dependencies.\n- Set up [Stale bot](https://github.com/apps/stale) for automatic issue closing.\n\n### Poetry\n\nWant to know more about Poetry? Check [its documentation](https://python-poetry.org/docs/).\n\n\u003cdetails\u003e\n\u003csummary\u003eDetails about Poetry\u003c/summary\u003e\n\u003cp\u003e\n\nPoetry's [commands](https://python-poetry.org/docs/cli/#commands) are very intuitive and easy to learn, like:\n\n- `poetry add numpy@latest`\n- `poetry run pytest`\n- `poetry publish --build`\n\netc\n\u003c/p\u003e\n\u003c/details\u003e\n\n### Building and releasing your package\n\nBuilding a new version of the application contains steps:\n\n- Bump the version of your package `poetry version \u003cversion\u003e`. You can pass the new version explicitly, or a rule such as `major`, `minor`, or `patch`. For more details, refer to the [Semantic Versions](https://semver.org/) standard.\n- Make a commit to `GitHub`.\n- Create a `GitHub release`.\n- And... publish 🙂 `poetry publish --build`\n\n\n\n## Installation\n\n```bash\npip install -U eyes3scribe\n```\n\nor install with `Poetry`\n\n```bash\npoetry add eyes3scribe\n```\n\nThen you can run\n\n```bash\neyes3scribe --help\n```\n\nor with `Poetry`:\n\n```bash\npoetry run eyes3scribe --help\n```\n\n### Makefile usage\n\n[`Makefile`](https://github.com/stablecaps/eyes3scribe/blob/master/Makefile) contains a lot of functions for faster development.\n\n\u003cdetails\u003e\n\u003csummary\u003e1. Download and remove Poetry\u003c/summary\u003e\n\u003cp\u003e\n\nTo download and install Poetry run:\n\n```bash\nmake poetry-download\n```\n\nTo uninstall\n\n```bash\nmake poetry-remove\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e2. Install all dependencies and pre-commit hooks\u003c/summary\u003e\n\u003cp\u003e\n\nInstall requirements:\n\n```bash\nmake install\n```\n\nPre-commit hooks coulb be installed after `git init` via\n\n```bash\nmake pre-commit-install\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e3. Codestyle\u003c/summary\u003e\n\u003cp\u003e\n\nAutomatic formatting uses `pyupgrade`, `isort` and `black`.\n\n```bash\nmake codestyle\n\n# or use synonym\nmake formatting\n```\n\nCodestyle checks only, without rewriting files:\n\n```bash\nmake check-codestyle\n```\n\n\u003e Note: `check-codestyle` uses `isort`, `black` and `darglint` library\n\nUpdate all dev libraries to the latest version using one comand\n\n```bash\nmake update-dev-deps\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e4. Code security\u003c/summary\u003e\n\u003cp\u003e\n\n```bash\nmake check-safety\n```\n\nThis command launches `Poetry` integrity checks as well as identifies security issues with `Safety` and `Bandit`.\n\n```bash\nmake check-safety\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e5. Type checks\u003c/summary\u003e\n\u003cp\u003e\n\nRun `mypy` static type checker\n\n```bash\nmake mypy\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e6. Tests with coverage badges\u003c/summary\u003e\n\u003cp\u003e\n\nRun `pytest`\n\n```bash\nmake test\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e7. All linters\u003c/summary\u003e\n\u003cp\u003e\n\nOf course there is a command to ~~rule~~ run all linters in one:\n\n```bash\nmake lint\n```\n\nthe same as:\n\n```bash\nmake test \u0026\u0026 make check-codestyle \u0026\u0026 make mypy \u0026\u0026 make check-safety\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e8. Docker\u003c/summary\u003e\n\u003cp\u003e\n\n```bash\nmake docker-build\n```\n\nwhich is equivalent to:\n\n```bash\nmake docker-build VERSION=latest\n```\n\nRemove docker image with\n\n```bash\nmake docker-remove\n```\n\nMore information [about docker](https://github.com/stablecaps/eyes3scribe/tree/master/docker).\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e9. Cleanup\u003c/summary\u003e\n\u003cp\u003e\nDelete pycache files\n\n```bash\nmake pycache-remove\n```\n\nRemove package build\n\n```bash\nmake build-remove\n```\n\nDelete .DS_STORE files\n\n```bash\nmake dsstore-remove\n```\n\nRemove .mypycache\n\n```bash\nmake mypycache-remove\n```\n\nOr to remove all above run:\n\n```bash\nmake cleanup\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\n## 📈 Releases\n\nYou can see the list of available releases on the [GitHub Releases](https://github.com/stablecaps/eyes3scribe/releases) page.\n\nWe follow [Semantic Versions](https://semver.org/) specification.\n\nWe use [`Release Drafter`](https://github.com/marketplace/actions/release-drafter). As pull requests are merged, a draft release is kept up-to-date listing the changes, ready to publish when you’re ready. With the categories option, you can categorize pull requests in release notes using labels.\n\n### List of labels and corresponding titles\n\n|               **Label**               |  **Title in Releases**  |\n| :-----------------------------------: | :---------------------: |\n|       `enhancement`, `feature`        |       🚀 Features       |\n| `bug`, `refactoring`, `bugfix`, `fix` | 🔧 Fixes \u0026 Refactoring  |\n|       `build`, `ci`, `testing`        | 📦 Build System \u0026 CI/CD |\n|              `breaking`               |   💥 Breaking Changes   |\n|            `documentation`            |    📝 Documentation     |\n|            `dependencies`             | ⬆️ Dependencies updates |\n\nYou can update it in [`release-drafter.yml`](https://github.com/stablecaps/eyes3scribe/blob/master/.github/release-drafter.yml).\n\nGitHub creates the `bug`, `enhancement`, and `documentation` labels for you. Dependabot creates the `dependencies` label. Create the remaining labels on the Issues tab of your GitHub repository, when you need them.\n\n## 🛡 License\n\n[![License](https://img.shields.io/github/license/stablecaps/eyes3scribe)](https://github.com/stablecaps/eyes3scribe/blob/master/LICENSE)\n\nThis project is licensed under the terms of the `Apache Software License 2.0` license. See [LICENSE](https://github.com/stablecaps/eyes3scribe/blob/master/LICENSE) for more details.\n\n## 📃 Citation\n\n```bibtex\n@misc{eyes3scribe,\n  author = {Stablecaps},\n  title = {Automatically creates HTML documentation files for BASH/Shell source code using markdown \u0026 python mkdocs},\n  year = {2024},\n  publisher = {GitHub},\n  journal = {GitHub repository},\n  howpublished = {\\url{https://github.com/stablecaps/eyes3scribe}}\n}\n```\n\n## Credits [![🚀 Your next Python package needs a bleeding-edge project structure.](https://img.shields.io/badge/python--package--template-%F0%9F%9A%80-brightgreen)](https://github.com/stablecaps/stablecaps-pycookiecutter-template)\n\nThis project was generated with [`python-package-template`](https://github.com/stablecaps/stablecaps-pycookiecutter-template)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstablecaps%2Feyes3scribe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstablecaps%2Feyes3scribe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstablecaps%2Feyes3scribe/lists"}