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 ./ in pipx install ./pykyll-SEMANTIC-VERSION-STRING.whl.
Version 0.1.4: Now who said Guten Berg? Atom Feed
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
pykyll check to make sure you are in line with your set pre commit hooks.pykyll status to check your repository statusWhen 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.
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.
Check out pykyll build --help for options
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()
Methods
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)
GNU General Public License v2.0., aka a cancer to proprietary software, although the maintainer prefers the term a vaccination.
by
Documentation build features are now controlled by option switches.
The journal is now rendered in reverse order in HTML documents, Displaying the body of the latest post first, followed by the heading, month, year.
This is the first post to pykylls blog as this feature just got enabled. 🚀 In conjunction with mopsman jrnl has become a welcome addition to the stack. Now its possible to generate a simple blog if you keep the README short.