Pykyll Documentation Automation Tool
This software is highly adapted to a particular work flow and not for everyone, though you may find it useful.
The documentation is generated together with
pykyll as it evolves.
This very page was generated from the
README.md and the developer jrnl.
pykylls aim is to lower personal maintenance cost in documentation of software projects and works for me.
Download the latest wheel and install to an ephemeral virtual environment handled by pipx.
Tip: Don't forget the
pipx install ./pykyll-SEMANTIC-VERSION-STRING.whl.
Work Flow. Starting out from any git repository generated by poetry.
poetry shell pykyll init
In case you are not developing with poetry, you may ignore the suggestions from the output and instead handle the virtual environment yourself.
During developemet pykyll simply stays out of the way. You may use it for having a api reference to your own code available. In this work flow pykyll may be deployed to check, build and serve or export the docs when for example
- the documentation has been updated.
- the code comments have been updated.
- the jrnl has been updated.
- the software version is bumped
pykyll checkto make sure you are in line with your set pre commit hooks.
pykyll statusto check your repository status
When running any of the following, please enter your development virtual environment either manually or by
poetry shell and invoke
pykyll from your git projects root folder.
This will turn your projects README.md into a mini site in
docs/html_out and generate a description from your code comments using
pdoc. Check out pykylls own web site at is has Gone and documented itself!
If you are keeping a jrnl, use the value for
name from the configuration file as a
@tag. Pykyll will stick the matching entries on to your README.md if run as
pykyll build -j, thus making for a simple micro blogging solution.
pykyll build --help for options
http.server to make the web site available on your own local host and thus not meant to be run in a production environment, as in exposed to the internet.
To get you going pykylls style shets are in the repositories
As all commands on this page intended to be executed from within your projects
poetry shell or virtual environment manages by other means and by no means intended for production use. This is simply checked by calling:
try: os.environ["VIRTUAL_ENV"] except KeyError: foo()
- SFTP Upload
Make yourself a
settings.py following this example.
echo "settings.py" >> .gitignore pykyll export
Please consider the importance of line 1.
As the name of the code style sheet is simply hard coded, you may change the source code or you may generate a style sheet as recommended in the official pygments docs like so:
pygmentize -S monokai -f html -a .codehilite > styles.css
Which naturally goes into your html_out as this is just a mini site to get something like this:
def serve(self): """Serve current docs version on localhost.""" self.base_check() # make sure we are in the right directory PORT = 8000 Handler = http.server.SimpleHTTPRequestHandler os.chdir("docs/html_out") # Contens of the docu mini site self.display_header() with socketserver.TCPServer(("", PORT), Handler) as httpd: print("\nServing on http://0.0.0.0:8000\n[bold]<Ctrl> + <c> to quit[/bold]") with self.cons.status("cya on port 8000", spinner="hearts"): try: httpd.serve_forever() except KeyboardInterrupt: self.cons.print("Bye") # with status: Use rich console print sys.exit(0)
- This list could and should certainly be generated programatically. ;)
GNU General Public License v2.0., aka a cancer to proprietary software, although the maintainer prefers the term a vaccination.