Automatically creates HTML documentation files for BASH/Shell source code using markdown & python mkdocs
This project is a Python application that uses pip for package management. The main entry point for the application is gen_mkdocs_site.py.
Features:
git clone <repository_url>
cd <project_directory>
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# Run program to create mkdocs documentation site and serve it locally.
python gen_mkdocs_site.py --site-confname config/bash_it_site.yaml ---build-serve
# Show help
python gen_mkdocs_site.py --help
--site_confname
(str): The name of the site configuration.--build_serve
(bool): Whether to build and serve the local MkDocs site.--check_singlefile
(str): The path of a single shell source file to debug.--debug
(bool, optional): If True, debug information will be printed. Defaults to False.Auto-Documatix Callgraph: (made with PyDeps)
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
This project is licensed under the Apache 2.0 License - see the LICENSE.md file for details.
git
inside your repo:cd eyes3scribe && git init
Poetry
installed run:make poetry-download
pre-commit
hooks:make install
make pre-commit-install
make codestyle
git add .
git commit -m ":tada: Initial commit"
git branch -M main
git remote add origin https://github.com/stablecaps/eyes3scribe.git
git push -u origin main
Want to know more about Poetry? Check its documentation.
Poetry's commands are very intuitive and easy to learn, like:
poetry add numpy@latest
poetry run pytest
poetry publish --build
etc
Building a new version of the application contains steps:
poetry version <version>
. You can pass the new version explicitly, or a rule such as major
, minor
, or patch
. For more details, refer to the Semantic Versions standard.GitHub
.GitHub release
.poetry publish --build
pip install -U eyes3scribe
or install with Poetry
poetry add eyes3scribe
Then you can run
eyes3scribe --help
or with Poetry
:
poetry run eyes3scribe --help
Makefile
contains a lot of functions for faster development.
To download and install Poetry run:
make poetry-download
To uninstall
make poetry-remove
Install requirements:
make install
Pre-commit hooks coulb be installed after git init
via
make pre-commit-install
Automatic formatting uses pyupgrade
, isort
and black
.
make codestyle
# or use synonym
make formatting
Codestyle checks only, without rewriting files:
make check-codestyle
Note:
check-codestyle
usesisort
,black
anddarglint
library
Update all dev libraries to the latest version using one comand
make update-dev-deps
make check-safety
This command launches Poetry
integrity checks as well as identifies security issues with Safety
and Bandit
.
make check-safety
Run mypy
static type checker
make mypy
Run pytest
make test
Of course there is a command to rule run all linters in one:
make lint
the same as:
make test && make check-codestyle && make mypy && make check-safety
make docker-build
which is equivalent to:
make docker-build VERSION=latest
Remove docker image with
make docker-remove
More information about docker.
make pycache-remove
Remove package build
make build-remove
Delete .DS_STORE files
make dsstore-remove
Remove .mypycache
make mypycache-remove
Or to remove all above run:
make cleanup
You can see the list of available releases on the GitHub Releases page.
We follow Semantic Versions specification.
We use Release Drafter
. As pull requests are merged, a draft release is kept up-to-date listing the changes, ready to publish when youre ready. With the categories option, you can categorize pull requests in release notes using labels.
Label | Title in Releases |
---|---|
enhancement , feature
|
Features |
bug , refactoring , bugfix , fix
|
Fixes & Refactoring |
build , ci , testing
|
Build System & CI/CD |
breaking |
Breaking Changes |
documentation |
Documentation |
dependencies |
Dependencies updates |
You can update it in release-drafter.yml
.
GitHub 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.
This project is licensed under the terms of the Apache Software License 2.0
license. See LICENSE for more details.
@misc{eyes3scribe,
author = {Stablecaps},
title = {Automatically creates HTML documentation files for BASH/Shell source code using markdown & python mkdocs},
year = {2024},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/stablecaps/eyes3scribe}}
}
This project was generated with python-package-template