Skip to content

Pykyll Documentation Automation Tool

pykyll badge
Supporting poetry, recommending pre-commit-hooks and generating a fully hackable mini web site from a project README.md and project code comments. Providing alternatives as text files or as a fancy web site running scripts all over the place - no ads - no tracking. Basically making this project: *Go, DOC yourself!*

This software is highly adapted to a particular work flow and not for everyone, though you may find it useful.

Documentation

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.

Install

Download the latest wheel and install to an ephemeral virtual environment handled by pipx.

Tip: Don't forget the ./ in pipx install ./pykyll-SEMANTIC-VERSION-STRING.whl.

Version 0.1.4: Now who said Guten Berg? Atom Feed

Automation

Work Flow. Starting out from any git repository generated by poetry.

Initialize

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.

Develope

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 check to make sure you are in line with your set pre commit hooks.
  • pykyll status to 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.

Build

pykyll build

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.

output of pykyll build
There are a couple of output options for your site. On pykylls own web site they are all switched on.

Check out pykyll build --help for options

Serve

pykyll serve

Using Pythons 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 docs/html_out.

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()

Export

Methods

  • SFTP Upload

Make yourself a settings.py following this example.

echo "settings.py" >> .gitignore
pykyll export

Please consider the importance of line 1.

Pygments

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)

Known Issues

  • This list could and should certainly be generated programatically. ;)

License

GNU General Public License v2.0., aka a cancer to proprietary software, although the maintainer prefers the term a vaccination.

Sites maintained with pykyll

pykyll self demo
mopsman: mom & dad
better letter
web cast catcher & player