Commit 5b0be7d5 authored by ak's avatar ak
Browse files

version 0.1.3

parent 2c0d1ba6
pages:
stage: deploy
script:
- cp -ru empty public
artifacts:
paths:
- public
only:
- master
tags:
- cluster
......@@ -10,10 +10,10 @@ repos:
- id: check-yaml
- id: check-added-large-files
- id: check-docstring-first
- id: check-json
- id: check-toml
- id: check-xml
- id: pretty-format-json
# - id: check-json
# - id: check-toml
# - id: check-xml
# - id: pretty-format-json
- repo: https://github.com/psf/black
rev: 21.10b0
hooks:
......@@ -23,13 +23,14 @@ repos:
# pre-commit's default_language_version, see
# https://pre-commit.com/#top_level-default_language_version
language_version: python3.9
# - repo: https://gitlab.com/pycqa/flake8
# rev: 3.9.2
# hooks:
# - id: flake8
# args:
# - --max-line-length=120
# additional_dependencies: [flake8-bugbear]
- repo: https://gitlab.com/pycqa/flake8
rev: 3.9.2
hooks:
- id: flake8
args:
- --max-line-length=120
- --ignore=B008, W503
additional_dependencies: [flake8-bugbear]
# - repo: https://github.com/pycqa/pydocstyle
# rev: 6.1.1 # pick a git hash / tag to point to
# hooks:
......
......@@ -5,3 +5,4 @@ export_dir: docs/html_out
language: en-en
name: pykyll
work_dir: /home/ak/git/pykyll
git: https://git.c3pb.de/ak/pykyll
# Pykyll Documentation
# Pykyll Documentation Automation Tool
*Effortless generation of documentation for Your Python project sensation.* 🙄
*Effortless generation of documentation for Your Python project sensation.* 🙄 Experimental.
Supporting [poetry](https://python-poetry.org/), recommending [pre-commit-hooks](https://pre-commit.com/) and generating a fully hackable mini web site from a project README.md and project code comments using [pdoc3](https://pdoc3.github.io/pdoc/). Providing alternatives as text files or as a fancy web site running scripts all over the place - no ads - no tracking. All while combining them and [other tools](https://git.c3pb.de/ak/pykyll/-/blob/master/requirements.txt) with a glue code Python class and making them into an opinionated work flow to make this project: *Go, document itself!*
<a href="https://pykyll.harmlos.info"><img class="icon" src="https://pykyll.harmlos.info/pykyll_logo.png"></a>
Hence, this software is highly adapted to a particular workflow and not for everyone, though you may find it usefull.
Supporting [poetry](https://python-poetry.org/), recommending [pre-commit-hooks](https://pre-commit.com/) and generating a fully hackable mini web site from a project README.md and project code comments using [pdoc3](https://pdoc3.github.io/pdoc/). Providing alternatives as text files or as a fancy web site running scripts all over the place - no ads - no tracking. All while combining them and [other tools](https://git.c3pb.de/ak/pykyll/-/blob/master/requirements.txt) with a glue code Python class and making them into an opinionated work flow to make this project: *Go, DOC yourself!*
<a href="https://pykyll.harmlos.info"><img class="icon" src="https://pykyll.harmlos.info/pykyll_logo.png"></a> <a href="https://ak.harmlos.info/#software"><img class="icon" src="https://harmlos.info/ak.png"></a>
You may download and unzip a archive of [this page](https://pykyll.harmlos.info/html_out.zip) to get you going into your `docs/html_out`.
Hence, this software is highly adapted to a particular work flow and not for everyone, though you may find it useful.
## Documentation
There are alternative ways of viewing the documentation.
- [Web Site](https://pykyll.harmlos.info/pykyll) generated by [pdoc3](https://pdoc3.github.io/pdoc/)
- [Fancy Web Site](https://pykyll.harmlos.info/site) generated by [portray](https://timothycrosley.github.io/portray/)
- [Text files](https://git.c3pb.de/ak/pykyll/-/tree/master/docs/pykyll) on gitlab.
Pykylls documentation is naturally generated with pykyll as it evolves. In this way the following alternate views into pykylls inner workings also serve as a comprehensive example of pykylls features.
Alternatives are smexy.
[Alternatives](#docs-projectpykyll) are smexy.
This very page was generated from the [`README.md`](https://git.c3pb.de/ak/pykyll/-/blob/master/README.md) and the developer jrnl.
`pykyll`s aim is to ease maintenance cost in documentation of software projects and works for me.
`pykyll`s aim is to lower personal maintenance cost in documentation of software projects and works for me.
### Install
Download the [latest wheel](https://git.c3pb.de/ak/pykyll/-/tree/master/dist) and install to an ephemeral virtual environment handled by pipx.
Tip: Don't forget the `./` in `pipx install ./pykyll-SEMANTIC-VERSION-STRING.whl`
Tip: Don't forget the `./` in `pipx install ./pykyll-SEMANTIC-VERSION-STRING.whl`.
### Worflow
## Work flow
Starting out from any git repository generated by [poetry]().
### Initialise and Check your already existing git repository
### Initialize
:::shell
poetry shell
......@@ -42,25 +36,47 @@ Starting out from any git repository generated by [poetry]().
In case you are not developing with poetry, you may ignore the suggestions from the output and instead handle the virtual environment yourself.
### Build docs sub folder
### 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.
and put the mini web site into `docs/html_out`.
### Build
:::shell
pykyll build
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!*
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 running a [jrnl](https://jrnl.sh/en/stable/), use the value for `name` from the configuration file as a `@tag`. Pykyll will stick the whole jrnl on to your README.md, thus making for an [micro blogging solution]().
If you are keeping a [jrnl](https://jrnl.sh/en/stable/), 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](https://pykyll.harmlos.info/site/docs/blog/).
### Lokal development web server
<figure>
<img src="https://pykyll.harmlos.info/pykyll_build.png" alt="output of pykyll build">
<figcaption>
There are a couple of output options for your site. On pykylls <a href="https://pykyll.harmlos.info/#docs-projectpykyll">own web site</a> they are all switched on.
</figcaption>
</figure>
Check out ```pykyll build --help``` for options
Using Pythons `http.server`
### Serve
:::shell
pykyll serve
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
Using Pythons `http.server` to make the web site available on your own [local host](http://0.0.0.0:8000) 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:
:::python
try:
......@@ -68,7 +84,11 @@ As all commands on this page intended to be executed from within your projects `
except KeyError:
foo()
#### SFTP Upload
### Export
Methods
- SFTP Upload
Make yourself a `settings.py` following [this example](https://git.c3pb.de/ak/pykyll/-/blob/master/TEMPLATE_settings.py).
......@@ -78,19 +98,7 @@ Make yourself a `settings.py` following [this example](https://git.c3pb.de/ak/py
Please consider the importance of line 1.
## Self Test
### H3
#### H4
##### H5
###### H6
> This is a quote
### Pygments
#### 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:
......@@ -116,7 +124,7 @@ Which naturally goes into your html_out as this is just a mini site to get somet
self.cons.print("Bye") # with status: Use rich console print
sys.exit(0)
## Sites maintained with pykyll
#### Sites maintained with pykyll
<figure><a href="https://pykyll.harmlos.info">
<img class="icon" src="https://pykyll.harmlos.info/pykyll_logo.png">
......
# Blog
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.
### 2021-12-18 22:34 sort out html_out.
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.
### 2021-12-05 16:45 First Post.
## December
# 2021
---
<a href="https://ak.harmlos.info/#software">
<img class="icon" src="https://harmlos.info/ak.png">
</a>
[TOC]
# Blog
# 2021
## December
### 2021-12-05 16:45 First Post.
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.
### 2021-12-18 22:34 sort out html_out.
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.
### 2021-12-05 16:45 First Post.
## December
# 2021
---
......
......@@ -10,7 +10,7 @@ Functions
: Produce HTML output and view.
`build()`
`build(jrnl_switch: bool = <typer.models.OptionInfo object>, portray_switch: bool = <typer.models.OptionInfo object>, pdoc_switch: bool = <typer.models.OptionInfo object>)`
: Build static web site in docs/html_out
......@@ -18,8 +18,8 @@ Functions
: Pykyll Documentation Fun.
`check()`
: Checks by looping pre-commit-hooks.
`check(loop_pre_commit_hooks: bool = <typer.models.OptionInfo object>)`
: Pre-commit-hooks.
`edit(new: bool = <typer.models.OptionInfo object>)`
......
......@@ -44,7 +44,7 @@ Init Pykyll Object
:
`edit(self, work_file='/home/ak/git/pykyll/README.md')`
: edit a file with vavourite editor.
: Edit.
`export_html_fs(self, work_dir, output_dir)`
: Recursive export
......@@ -66,14 +66,14 @@ output_dir (str, optional): [description]. Defaults to "".
Returns:
[type]: [description]
`inject_jrnl(self)`
`inject_jrnl_and_process_README(self)`
: Inject jrnl into html output
`inject_portray(self)`
: Inject jrnl into html output
: Inject portray into html output
`make_docs(self)`
: check content_directories recursively
`make_docs(self, portray_switch=False, jrnl_switch=False, pdoc_switch=False)`
: Make docs according to options into docs/html_out.
`pause(self, prompt='Press Any Key')`
: Pause, return key presssed Screen.
......@@ -81,6 +81,9 @@ Returns:
`print(self, stringy)`
:
`process_README(self)`
: Process README.md not injecting jrnl into html output.
`read(self)`
: Read docs in the termnal.
......@@ -90,9 +93,6 @@ Returns:
`select_fuzzy(self, work_dir='/home/ak/git/pykyll')`
: docstring
`select_post(self, work_dir='/home/ak/git/pykyll')`
:
`select_topic(self, work_dir='/home/ak/git/pykyll')`
:
......
"""Command Line Interface to Pykyll Documentation Tool."""
import os
import re
import sys
import typer
import shutil
# import requests
from time import sleep
......@@ -17,7 +14,6 @@ from rich import print
from pathlib import Path
from datetime import datetime
from timew import TimeWarrior
from pykyll.pykyll import Pykyll
......@@ -46,9 +42,9 @@ pkll = Pykyll(global_conf=config_path)
def callback(ctx: typer.Context):
"""Pykyll Documentation Fun."""
sys.stdout.write("\x1b]2;" + "pykyll:" + pkll.conf["name"] + "\x07")
if ctx.invoked_subcommand == None:
if ctx.invoked_subcommand is None:
pkll.cons.clear()
pkll.display_header("Pykyll Help")
pkll.display_header("Help")
pkll.cons.print(
"pykyll must be run from within your projects virtual environment: ", end=""
)
......@@ -68,7 +64,7 @@ def init():
"""
ok = True
pkll.cons.clear()
pkll.display_header("Pykyll Init")
pkll.display_header("Init")
if os.path.isfile(pkll.CONFIG):
pass
else:
......@@ -90,13 +86,15 @@ def init():
pkll.print("author:\t\t" + pkll.conf["author"])
loop_end = True
except KeyError as identifier: # missing frontmatter
# pkll.print("[black on magenta]README.MD")
# pkll.print("[black on bright_black]README.MD")
if "name" in str(identifier):
pkll.print(
"\nA Name for your project is [red]missing[/red].\n"
+ "Hint: This is by default the folder and the git name."
)
pkll.cons.rule(title="[magenta]Name", align="left", style="magenta")
pkll.cons.rule(
title="[bright_black]Name", align="left", style="bright_black"
)
pkll.conf["name"] = pkll.sess.prompt(default=pkll.conf["name"])
post["name"] = pkll.conf["name"]
elif "language" in str(identifier):
......@@ -107,6 +105,18 @@ def init():
elif "author" in str(identifier):
pkll.conf["author"] = getuser()
post["author"] = pkll.conf["author"]
pkll.print(
"\nDoes your project have a remote git repository?\n"
+ "Like all settings this can be changed in `.pykyll-config.yml`"
)
pkll.cons.rule(
title="[bright_black]Git remote URL",
align="left",
style="bright_black",
)
pkll.conf["git"] = pkll.sess.prompt()
if pkll.conf["git"] == "":
pkll.conf["git"] = "None"
pkll.serialize()
with open("docs/index.md", "w") as f:
f.writelines(frontmatter.dumps(post))
......@@ -128,7 +138,9 @@ def init():
pkll.cons.rule()
pkll.print(markeddown)
pkll.print("Now, after reviewing README.md, what should be the title?")
pkll.cons.rule(title="[magenta]Title", align="left", style="magenta")
pkll.cons.rule(
title="[bright_black]Title", align="left", style="bright_black"
)
pkll.title = pkll.sess.prompt(default=os.getcwd().split("/")[-1])
post.content = "# " + pkll.title + "\n\n" + post.content
with open("README.md", "w") as f:
......@@ -147,7 +159,7 @@ def init():
pkll.print(
"So "
+ os.getcwd()
+ " is to be documented with [bold magenta]pykyll[/bold magenta],..\n"
+ " is to be documented with [bold bright_black]pykyll[/bold bright_black],..\n"
)
with pkll.cons.status("wait for it"):
sleep(1)
......@@ -157,14 +169,22 @@ def init():
"A Title is [red]missing[/red]. Please provide one.\n"
+ "Hint: This is the Heading 1."
)
pkll.cons.rule(title="[magenta]Title", align="left", style="magenta")
pkll.cons.rule(title="[bright_black]Title", align="left", style="bright_black")
pkll.conf["title"] = pkll.sess.prompt(default=pkll.conf["title"])
pkll.print(
"\nA Name for your project is [red]missing[/red].\n"
+ "Hint: Oftentimes this is the folder or git name."
)
pkll.cons.rule(title="[magenta]Name", align="left", style="magenta")
pkll.cons.rule(title="[bright_black]Name", align="left", style="bright_black")
pkll.conf["name"] = pkll.sess.prompt(default=pkll.conf["name"])
pkll.print(
"\nDoes your project have a remote git repository?\n"
+ "Like all settings this can be changed in `.pykyll-config.yml`"
)
pkll.cons.rule(
title="[bright_black]Git remote URL", align="left", style="bright_black"
)
pkll.conf["git"] = pkll.sess.prompt(default=pkll.conf["git"])
pkll.print(
"\nSpell checking language [red]missing[/red].\n" + "Hint: Used by vi."
)
......@@ -210,8 +230,8 @@ def init():
sleep(1)
if ok:
pkll.print(
f"[magenta]{pkll.title}"
+ "[/magenta] [green]✔[/green] checked out to be ready for more docu fun.\n"
f"[bright_black]{pkll.title}"
+ "[/bright_black] [green]✔[/green] checked out to be ready for more docu fun.\n"
)
# pkll.print("Hint: `pykyll status`, `pykyll serve`")
else:
......@@ -224,7 +244,7 @@ def browse(publish: bool = typer.Option(default=False, help="Publish")):
"""Produce HTML output and view."""
init()
pkll.base_check()
pkll.display_header("Pykyll building docs and docs/html")
pkll.display_header("building docs and docs/html")
pkll.make_docs()
pkll.serve()
pkll.print("Browse Command: Not yet implemented.")
......@@ -234,7 +254,7 @@ def browse(publish: bool = typer.Option(default=False, help="Publish")):
def jrnl():
"""Inject jrnl into html output"""
# init()
pkll.display_header("Pykyll injecting jrnl into docs/html")
pkll.display_header("injecting jrnl into docs/html")
pkll.base_check()
project_name = pkll.conf["name"]
output = os.popen("jrnl @" + project_name + " --format=md").readlines()
......@@ -259,16 +279,27 @@ def testout():
@app.command()
def build():
def build(
jrnl_switch: bool = typer.Option(
False, "--jrnl", "-j", help="Include jrnl in docs.."
),
portray_switch: bool = typer.Option(
False, "--portray", "-p", help="Spawn fancy doc web site."
),
pdoc_switch: bool = typer.Option(
False, "--pdoc3", "-3", help="Generate docs from doc strings."
),
):
"""Build static web site in docs/html_out"""
init()
pkll.display_header("Pykyll building docs and docs/html")
pkll.display_header("building docs and docs/html")
pkll.base_check()
pkll.make_docs()
# jrnl()
pkll.display_header("Pykyll pre-commit hooks")
check()
# pkll.print("Build Command: Not yet implemented.")
pkll.make_docs(
portray_switch=portray_switch, jrnl_switch=jrnl_switch, pdoc_switch=pdoc_switch
)
check(
loop_pre_commit_hooks=False
) # not looping as we may want want to run it ; pykyll serve
@app.command()
......@@ -278,11 +309,11 @@ def status():
Uses [onefetch](https://github.com/o2sh/onefetch) if avaiable to print a nice git summary.
"""
pkll.cons.clear()
pkll.display_header("Pykyll Repository Status")
pkll.display_header("Repository Status")
pkll.base_check()
try:
os.system("onefetch")
pkll.display_header("Pykyll Git Status and History")
pkll.display_header("Git Status and History")
except Exception:
pass
......@@ -307,17 +338,17 @@ def status():
# del t
# REWORK AND SHORTEN END
with pkll.cons.status("[magenta]" + tags + "\n"):
with pkll.cons.status("[bright_black]" + tags + "\n"):
sleep(3)
os.system("git status -bs")
pkll.print("\n[magenta]" + tags)
pkll.print("\n[bright_black]" + tags)
pkll.print("")
os.system("git shortlog | tail -n 5 | tac | tail -n 4")
with pkll.cons.status("[magenta]Table of Contents"):
with pkll.cons.status("[bright_black]Table of Contents"):
pkll.print("")
sleep(3)
......@@ -325,8 +356,12 @@ def status():
@app.command()
def check():
"""Checks by looping pre-commit-hooks."""
def check(
loop_pre_commit_hooks: bool = typer.Option(
False, "--loop", "-l", help="Loop pre-commit-hooks."
)
):
"""Pre-commit-hooks."""
loop_end = False
while not loop_end:
pkll.display_header("git status")
......@@ -335,7 +370,10 @@ def check():
os.system("git add .")
os.system(".git/hooks/pre-commit")
print("")
char = pkll.pause("<a> to loop again.")
if loop_pre_commit_hooks:
char = pkll.pause("<a> to run pre-commit-hooks again.")
else:
char = "n"
if not char == "a":
loop_end = True
......
......@@ -5,16 +5,13 @@ import filecmp
import http.server
import json
import os
import re
import shutil
import socketserver
import subprocess
import sys
import threading
import time
import portray.api as portray
# import portray.api as portray
# import webbrowser
import getch
......@@ -32,7 +29,7 @@ from prompt_toolkit import PromptSession
from rich import print
from rich.console import Console
from rich.markdown import Markdown
from rich.prompt import Confirm, Prompt
from rich.prompt import Prompt
# from rich.text import Text
from rich.table import Table
......@@ -41,7 +38,6 @@ from rich.traceback import install
from pykyll.menutools import (
menu,
menu_preview,
menu_preview_show_item,
preview,
shorten,
sorted_nicely,
......@@ -95,7 +91,7 @@ class Pykyll:
# self.conf.update({"title": "CHANGE ME [e] Edit –> .config.yml"})
# pconfig = sorted_nicely(pconfig)
with open(self.CONFIG, "w") as f:
_data = yaml.dump(self.conf, f)
yaml.dump(self.conf, f)
# print(_data)
sleep(5)
......@@ -121,7 +117,7 @@ class Pykyll:
"""
# print("[bold]Serialize[/bold]")
with open(self.CONFIG, "w") as f:
_data = yaml.dump(self.conf, f)
yaml.dump(self.conf, f)
try:
os.remove(".tableofcontents.json")
except FileNotFoundError:
......@@ -165,7 +161,7 @@ class Pykyll:
style="red",
no_wrap=True,
)
table.add_column(check_dir, style="bold magenta")
table.add_column(check_dir, style="bold bright_black")
for item in items:
table.add_row(item, str(post[item]))
cons.print(table)
......@@ -192,7 +188,7 @@ class Pykyll:
with open(current_file, "w") as f:
f.writelines(frontmatter.dumps(post))