documentation: generate tables of content, better navigation

my/core/init.py

@@ -41,7 +41,10 @@ def setup_config() -> None:
         mycfg_dir = Path(appdirs.user_config_dir('my'))
 
     if not mycfg_dir.exists():
-        warnings.warn(f"my.config package isn't found! (expected at {mycfg_dir}). This is likely to result in issues.")
+        warnings.warn(f"""
+'my.config' package isn't found! (expected at {mycfg_dir}). This is likely to result in issues.
+See https://github.com/karlicoss/HPI/blob/master/doc/SETUP.org#setting-up-the-modules for more info.
+""".strip())
         return
 
     mpath = str(mycfg_dir)
@@ -58,10 +61,12 @@ def setup_config() -> None:
         import my.config
     except ImportError as ex:
         # just in case... who knows what crazy setup users have in mind.
-        warnings.warn(f"Importing my.config failed! (error: {ex}). This is likely to result in issues.")
+        # todo log?
+        warnings.warn(f"""
+Importing 'my.config' failed! (error: {ex}). This is likely to result in issues.
+See https://github.com/karlicoss/HPI/blob/master/doc/SETUP.org#setting-up-the-modules for more info.
+""")
 
 
 setup_config()
 del setup_config
-
-# TODO move to my.core?

my/hypothesis.py

@@ -19,7 +19,7 @@ class hypothesis(user_config):
     export_path: Paths
 
     # path to a local clone of hypexport
-    # alternatively, you can put the repository (or a symlink) in $MY_CONFIG/repos/hypexport
+    # alternatively, you can put the repository (or a symlink) in $MY_CONFIG/my/config/repos/hypexport
     hypexport  : Optional[PathIsh] = None
 
     @property

my/instapaper.py

@@ -18,7 +18,7 @@ class instapaper(user_config):
     export_path : Paths
 
     # path to a local clone of instapexport
-    # alternatively, you can put the repository (or a symlink) in $MY_CONFIG/repos/instapexport
+    # alternatively, you can put the repository (or a symlink) in $MY_CONFIG/my/config/repos/instapexport
     instapexport: Optional[PathIsh] = None
 
     @property

my/reddit.py

@@ -19,7 +19,7 @@ class reddit(uconfig):
     export_path: Paths
 
     # path to a local clone of rexport
-    # alternatively, you can put the repository (or a symlink) in $MY_CONFIG/repos/rexport
+    # alternatively, you can put the repository (or a symlink) in $MY_CONFIG/my/config/repos/rexport
     rexport    : Optional[PathIsh] = None
 
     @property