version 0.1.3

.gitlab-ci.yml

-pages:
-  stage: deploy
-  script:
-    - cp -ru empty public
-  artifacts:
-    paths:
-    - public
-  only:
-  - master
-  tags:
-  - cluster

.pre-commit-config.yaml

@@ -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:

.pykyll_config.yml

@@ -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

README.md

-# 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.md

+# 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]

docs/blog.md

 # 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
 
 
 ---

docs/pykyll/main.md

@@ -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>)`

docs/pykyll/pykyll.md

@@ -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')`
 :
 

empty/index.html

-It works!

pykyll/main.py

 """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
 

pykyll/pykyll.py

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