Add auto-generated module documentation for Sphinx

The Sphinx now automatically documents the plugins module. Signed-off-by: Heikki Laaksonen <laaksonen.heikki.j@gmail.com>
heilaaks · Jun 22, 2019 · 6aae050 · 6aae050
1 parent 74a1c8f
commit 6aae050
Show file tree

Hide file tree

Showing 5 changed files with 46 additions and 29 deletions.
diff --git a/TODO.md b/TODO.md
@@ -10,6 +10,7 @@
    - [ ] Fix mocks and import failures when Snippy is released with the Plugins module.
    - [ ] Fix only needed constants in snippy.plugin.Const. Do not inherit all by default.
    - [ ] Fix one parse failure when importing tldr/pages.zh.
+   - [ ] Fix make docs that runs the docs from site-pages, not from local foler. Why?
 
 ## PACKAGING
    - [ ] none

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -54,7 +54,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ['static']
 
 # -- Options for HTML output -------------------------------------------------
 

diff --git a/docs/source/development.rst b/docs/source/development.rst
@@ -68,3 +68,19 @@ Relasing
       make clean-all
       python setup.py sdist bdist_wheel
       twine upload dist/*
+
+Modules
+-------
+
+snippy_tldr.plugin
+~~~~~~~~~~~~~~~~~~
+
+Description
+```````````
+
+Design
+``````
+
+.. automodule:: snippy_tldr.plugin
+   :members:
+   :member-order: bysource
diff --git a/docs/source/static/empty.git b/docs/source/static/empty.git
diff --git a/snippy_tldr/plugin.py b/snippy_tldr/plugin.py
@@ -51,38 +51,36 @@ def snippy_import_hook(logger, uri, validator, parser):
 
     The ``tldr man pages`` project seems use term ``page`` loosely in different
     contexts. In order to try to provide a bit more maintainable code, a more
-    detailed terms have been invented for this project.
-
-    ```
-    # Tldr man pages hierarchical layers.
-    #
-    # translations        pages        tldr files
-    # ============       =======       ==========
-      pages.it     +
-      pages.pt-BR  |
-      pages.zh     |
-      pages        +---+ common  +
-                       | linux   |
-                       | osx     |
-                       | sunos   |
-                       + windows +---+
-                                     |
-                                     + alpine.md
-                                       apk.md
-    ```
-
-    ==================  ===================================================================
+    detailed terms have been invented for this project::
+
+        # Tldr man pages hierarchical layers.
+        #
+        # translations        pages        tldr files
+        # ============       =======       ==========
+          pages.it     +
+          pages.pt-BR  |
+          pages.zh     |
+          pages        +---+ common  +
+                           | linux   |
+                           | osx     |
+                           | sunos   |
+                           + windows +---+
+                                         |
+                                         + alpine.md
+                                           apk.md
+
+    ==================  ======================================================================
     Term                Decscription
-    ==================  ===================================================================
+    ==================  ======================================================================
     *page*              |  A single tldr page like ``common``, ``linux`` or ``windows``.
 
     *pages*             |  All tldr pages under one translation.
 
-    *translation*       |  Tldr man page page translation like ``pages.it`` or ``pages.zh``.
+    *translation*       |  A tldr man page page translation like ``pages.it`` or ``pages.zh``.
 
-    *tldr files         |  A single tldr man page Markdown file. The term ``tldr man page``
-                        |  is not used in order to avoid confusion with term ``page``.
-    ==================  ===================================================================
+    *tldr files*        |  A single tldr man page Markdown file. The term ``tldr man page`` is not used in order to
+                        |  avoid confusion with term ``page``.
+    ==================  ======================================================================
 
     Args
         validate (obj): A ``SnippyNotesValidator`` object to validate JSON notes.
@@ -265,10 +263,12 @@ def __iter__(self):
         return self
 
     def next(self):
-        """Return the next snippet.
+        """Return the next tldr man page.
+
+        The returned pages are pre-formatted for Snippy tool.
 
         Returns:
-            dict: The next note in interator.
+            dict: The next tldr mage in interator.
         """
 
         if self._i < len(self):