#54: Add docs, fix issues in docs

docs/source/usage/custom-distribution.rst

@@ -85,3 +85,14 @@ Example
 
 Read more in :ref:`global environment variables`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Customizing RKD resource files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Files like banner, internal Makefiles can be overridden in user's home directory, or in operating system-wide directory.
+
+Here is the priority list, first matching result stops the search:
+
+.. include:: ../../rkd/packaging.py
+   :start-after: <sphinx_resources-get_possible_paths>
+   :end-before: </sphinx_resources-get_possible_paths>

docs/source/usage/tasks-api.rst

@@ -37,7 +37,7 @@ Storing temporary files
 
 Parsing RKD syntax
 ------------------
-.. autoclass:: rkd.api.syntax.SyntaxParsing
+.. autoclass:: rkd.api.parsing.SyntaxParsing
    :members:
 
 Testing

rkd/api/contract.py

@@ -201,6 +201,7 @@ def get_arg_or_env(self, name: str) -> Union[str, None]:
             Below example maps "COMMAND" environment variable to "--cmd" switch.
 
             .. code:: python
+
                 def get_declared_envs(self) -> Dict[str, Union[str, ArgumentEnv]]:
                     return {
                         'COMMAND': ArgumentEnv(name='COMMAND', switch='--cmd', default='')

rkd/api/inputoutput.py

@@ -388,12 +388,13 @@ def ask(self, title: str, attribute: str, regexp: str = '', to_env: bool = False
         """Asks user a question
 
         Usage:
-            wizard = Wizard(self)
-            wizard.ask('In which year the Spanish social revolution has begun?',
-                       attribute='year',
-                       choices=['1936', '1910'])
-            wizard.finish()
+            .. code:: python
 
+                wizard = Wizard(self)
+                wizard.ask('In which year the Spanish social revolution has begun?',
+                           attribute='year',
+                           choices=['1936', '1910'])
+                wizard.finish()
         """
 
         retried = 0

rkd/packaging.py

@@ -27,6 +27,7 @@ def get_possible_paths(path: str) -> List[str]:
     :return:
     """
 
+    # <sphinx_resources-get_possible_paths>
     paths = [
         # eg. ~/.local/share/rkd/banner.txt
         os.path.expanduser('~/.local/share/rkd/' + path),
@@ -40,6 +41,7 @@ def get_possible_paths(path: str) -> List[str]:
         # eg. /usr/share/rkd/banner.txt
         '/usr/share/rkd/' + path
     ]
+    # </sphinx_resources-get_possible_paths>
 
     # eg. ./rkd/misc/banner.txt
     global_module_path = _get_current_script_path() + '/misc/' + path