chg: doc: refactor doc extensions to use apidoc, add docs logo icon

* cleanup more docstrings and sphinx modules, update changelog again

Signed-off-by: Stephen Arnold <[email protected]>

CHANGELOG.rst

@@ -1,6 +1,7 @@
 Changelog
 =========
 
+
 0.2.0 (2024-08-25)
 ------------------
 
@@ -13,6 +14,14 @@ New
 
 Changes
 ~~~~~~~
+- Refactor doc extensions to use apidoc, add docs logo icon. [Stephen
+  Arnold]
+
+  * cleanup more docstrings and sphinx modules
+- Update changelog for next version, remove sphinx git hash. [Stephen
+  Arnold]
+
+  * also suppress duplicate label warnings from autosectionlabel
 - Respin doc symlinks using vendored copies. [Stephen Arnold]
 - Update docs and packaging, post refactoring cleanup. [Stephen Arnold]
 

docs/source/conf.py

@@ -18,7 +18,8 @@
 else:
     from importlib.metadata import version
 
-sys.path.insert(0, os.path.abspath('../../src/timew_status'))
+sys.path.insert(0, os.path.abspath('../..'))
+sys.path.insert(0, os.path.abspath('../../src'))
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
@@ -36,29 +37,48 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-    'sphinx_git',
     'rst2pdf.pdfbuilder',
-    'sphinx.ext.autodoc',
+    'sphinxcontrib.apidoc',
     'sphinx.ext.doctest',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.autosectionlabel',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
 ]
 
-suppress_warnings = ['autosectionlabel.*']
+apidoc_module_dir = '../../src/timew_status/'
+apidoc_output_dir = 'api'
+apidoc_excluded_paths = ['tests', 'scripts']
+apidoc_separate_modules = True
 
 templates_path = ['_templates']
 
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.venv']
 
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'sphinx_rtd_theme'
+html_logo = 'gh/images/timew.png'
 #html_static_path = ['_static']
-html_sidebars = {'**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']}
+html_sidebars = {
+    '**': [
+        'relations.html',  # needs 'show_related': True theme option to display
+        'searchbox.html',
+    ]
+}
+
+html_theme_options = {
+    # Toc options
+    'collapse_navigation': True,
+    'sticky_navigation': True,
+    'navigation_depth': 4,
+}
 
 source_suffix = {'.rst': 'restructuredtext'}
 master_doc = "index"

docs/source/gh/images/timew.png

@@ -0,0 +1 @@
+../../../../gh/images/timew.png

docs/source/index.rst

@@ -11,16 +11,12 @@ The primary timewarrior_ addon bits included here are written in Python_:
 .. _timewarrior: https://timewarrior.net/docs/install/
 .. _timew-report: https://pypi.org/project/timew-report/
 
-.. git_commit_detail::
-  :uncommitted:
-  :untracked:
-
 .. toctree::
-  :maxdepth: 3
+  :maxdepth: 2
   :caption: Contents:
 
   README
-  modules
+  api/modules
   CHANGELOG
 
 Indices and tables

setup.cfg

@@ -74,6 +74,7 @@ doc =
     sphinx
     sphinx_git
     sphinx_rtd_theme
+    sphinxcontrib-apidoc
     rst2pdf[svgsupport]
 test =
     pytest

src/timew_status/utils.py

@@ -34,6 +34,10 @@ def do_install(cfg):
     Install report extensions to timew extensions directory. The default
     paths are preconfigured and should probably not be changed unless you
     know what you are doing, since *they are created during install or setup*.
+    Return a destination path string for each installed extension script.
+
+    :param cfg: runtime CFG dict
+    :return files: list of strings
     """
     prefix = cfg["install_prefix"]
     srcdir = Path(prefix) / cfg["install_dir"]
@@ -56,8 +60,9 @@ def do_install(cfg):
 def get_config(file_encoding='utf-8'):
     """
     Load configuration file and munchify the data. If local file is not
-    found in config directory, the default will be loaded.  Return a
-    Munch cfg obj and corresponding Path obj.
+    found in config directory, the default will be loaded and saved to
+    XDG config directory. Return a Munch cfg obj and corresponding Path
+    obj.
 
     :param file_encoding: file encoding of config file
     :type file_encoding: str
@@ -66,6 +71,7 @@ def get_config(file_encoding='utf-8'):
     cfgdir = get_userdirs()
     cfgfile = cfgdir.joinpath('config.yaml')
     if not cfgfile.exists():
+        print(f"Saving initial config data to {cfgfile}")
         cfgfile.write_text(Munch.toYAML(CFG), encoding=file_encoding)
     cfgobj = Munch.fromYAML(cfgfile.read_text(encoding=file_encoding))
 
@@ -77,6 +83,7 @@ def get_delta_limits(ucfg):
     Return config max/snooze limits as timedeltas. Everything comes from
     static config values and gets padded with seconds.
 
+    :param ucfg: runtime CFG dict
     :return: tuple of 4 timedeltas
     """
     cfg = Munch.fromDict(ucfg)
@@ -98,6 +105,8 @@ def get_state_icon(state, cfg):
 
     :param state: name of state key
     :type state: str
+    :param cfg: runtime CFG (dict)
+
     :return: matching icon name (str)
     """
     install_path = '/usr/share/icons/hicolor/scalable/apps'
@@ -136,6 +145,8 @@ def get_state_str(cmproc, count, cfg):
     :type cmproc: CompletedProcess
     :param count: seat time counter value
     :type count: timedelta
+    :param cfg: runtime CFG
+    :type cfg: Dict
 
     :return: tuple of state msg and state string
     """

tox.ini

@@ -272,4 +272,5 @@ deps =
     pip>=21.1
 
 commands =
-    bash -c 'rm -rf __pycache__ .coverage.py* build dist docs/sum/sum/*.pdf src/*.egg-info src/*/__pycache__'
+    bash -c 'rm -rf __pycache__ .coverage.* build dist docs/source/api/'
+    bash -c 'rm -rf docs/sum/sum/*.pdf src/*.egg-info src/*/__pycache__'