From f193f94eef2b9844a41649b186c504b8c8221cb5 Mon Sep 17 00:00:00 2001
From: Stefano Pigozzi <ste.pigozzi@gmail.com>
Date: Tue, 10 Dec 2019 17:39:11 +0100
Subject: [PATCH] Autodocumentation improvements

---
 .idea/codeStyles/Project.xml | 24 +++++++++++++++++++++
 .idea/royalnet.iml           |  2 +-
 royalnet/backpack/README.md  | 41 ++++++++++++++++++++++++++++++++++--
 royalnet/generate.py         | 22 ++++++++++++++++++-
 4 files changed, 85 insertions(+), 4 deletions(-)

diff --git a/.idea/codeStyles/Project.xml b/.idea/codeStyles/Project.xml
index 3cdc6aed..49f7b87b 100644
--- a/.idea/codeStyles/Project.xml
+++ b/.idea/codeStyles/Project.xml
@@ -24,5 +24,29 @@
         <option name="ITERATION_ELEMENTS_WRAPPING" value="chop_down_if_not_single" />
       </formatting-settings>
     </DBN-SQL>
+    <DBN-PSQL>
+      <case-options enabled="true">
+        <option name="KEYWORD_CASE" value="lower" />
+        <option name="FUNCTION_CASE" value="lower" />
+        <option name="PARAMETER_CASE" value="lower" />
+        <option name="DATATYPE_CASE" value="lower" />
+        <option name="OBJECT_CASE" value="preserve" />
+      </case-options>
+      <formatting-settings enabled="false" />
+    </DBN-PSQL>
+    <DBN-SQL>
+      <case-options enabled="true">
+        <option name="KEYWORD_CASE" value="lower" />
+        <option name="FUNCTION_CASE" value="lower" />
+        <option name="PARAMETER_CASE" value="lower" />
+        <option name="DATATYPE_CASE" value="lower" />
+        <option name="OBJECT_CASE" value="preserve" />
+      </case-options>
+      <formatting-settings enabled="false">
+        <option name="STATEMENT_SPACING" value="one_line" />
+        <option name="CLAUSE_CHOP_DOWN" value="chop_down_if_statement_long" />
+        <option name="ITERATION_ELEMENTS_WRAPPING" value="chop_down_if_not_single" />
+      </formatting-settings>
+    </DBN-SQL>
   </code_scheme>
 </component>
\ No newline at end of file
diff --git a/.idea/royalnet.iml b/.idea/royalnet.iml
index d2034fcf..0b92a2cf 100644
--- a/.idea/royalnet.iml
+++ b/.idea/royalnet.iml
@@ -9,7 +9,7 @@
       <excludeFolder url="file://$MODULE_DIR$/docs" />
       <excludeFolder url="file://$MODULE_DIR$/royalnet.egg-info" />
     </content>
-    <orderEntry type="jdk" jdkName="Python 3.8 (royalnet-Yo3bJ6Dg-py3.8)" jdkType="Python SDK" />
+    <orderEntry type="jdk" jdkName="Python 3.8 (royalnet-1MWM6-kd-py3.8)" jdkType="Python SDK" />
     <orderEntry type="sourceFolder" forTests="false" />
   </component>
   <component name="TestRunnerService">
diff --git a/royalnet/backpack/README.md b/royalnet/backpack/README.md
index 0121370f..7dac7b1b 100644
--- a/royalnet/backpack/README.md
+++ b/royalnet/backpack/README.md
@@ -1,3 +1,40 @@
-# `backpack`
+<!--This documentation was autogenerated with `python -m royalnet.generate -f markdown`.-->
+
+# `royalnet.backpack`
+
+A Pack that is imported by default by all Royalnet instances.
+
+Keep things here to a minimum!
+
+## Commands
+
+### `version`
+
+Display the current Royalnet version.
+
+### `exception`
+
+Raise an exception in the command.
+
+### `excevent`
+
+Call an event that raises an exception.
+
+## Events
+
+### `exception`
+
+## Page Stars
+
+### `/api/royalnet/version`
+
+## Exception Stars
+
+## Tables
+
+### `telegram`
+
+### `discord`
+
+### `users`
 
-A Pack that is imported by default by all `royalnet` instances.
diff --git a/royalnet/generate.py b/royalnet/generate.py
index 62c06b96..5462d22d 100644
--- a/royalnet/generate.py
+++ b/royalnet/generate.py
@@ -42,10 +42,15 @@ def run(config_filename, file_format):
                 p(line)
 
     elif file_format == "markdown":
+        p("<!--This documentation was autogenerated with `python -m royalnet.generate -f markdown`.-->")
+        p("")
         for pack_name in packs:
             pack = packs[pack_name]
-            p(f"# {pack_name}")
+            p(f"# `{pack_name}`")
             p("")
+            if pack.__doc__:
+                p(f"{pack.__doc__}")
+                p("")
 
             try:
                 commands = pack.available_commands
@@ -59,6 +64,9 @@ def run(config_filename, file_format):
                     p("")
                     p(f"{command.description}")
                     p("")
+                    if command.__doc__:
+                        p(f"{command.__doc__}")
+                        p("")
                     if len(command.aliases) > 0:
                         p(f"> Aliases: {''.join(['`' + alias + '` ' for alias in command.aliases])}")
                         p("")
@@ -73,6 +81,9 @@ def run(config_filename, file_format):
                 for event in events:
                     p(f"### `{event.name}`")
                     p("")
+                    if event.__doc__:
+                        p(f"{event.__doc__}")
+                        p("")
 
             try:
                 page_stars = pack.available_page_stars
@@ -84,6 +95,9 @@ def run(config_filename, file_format):
                 for page_star in page_stars:
                     p(f"### `{page_star.path}`")
                     p("")
+                    if page_star.__doc__:
+                        p(f"{page_star.__doc__}")
+                        p("")
 
             try:
                 exc_stars = pack.available_exception_stars
@@ -95,6 +109,9 @@ def run(config_filename, file_format):
                 for exc_star in exc_stars:
                     p(f"### `{exc_star.error}`")
                     p("")
+                    if exc_star.__doc__:
+                        p(f"{exc_star.__doc__}")
+                        p("")
 
             try:
                 tables = pack.available_tables
@@ -107,6 +124,9 @@ def run(config_filename, file_format):
                     p(f"### `{table.__tablename__}`")
                     p("")
                     # TODO: list columns
+                    if table.__doc__:
+                        p(f"{table.__doc__}")
+                        p("")
 
     else:
         raise click.ClickException("Unknown format")