Merge pull request #6 from sarnold/doc-fixes

Give docs their own icons

CHANGELOG.rst

@@ -2,7 +2,34 @@ Changelog
 =========
 
 
-0.1.1 (2024-08-19)
+0.2.0 (2024-08-25)
+------------------
+
+New
+~~~
+- Add menu option to install extensions, beef up tests. [Stephen Arnold]
+
+  * add some pytest fixtures and more tests, improve readme
+  * refactor for correctness and testability, cleanup packaging
+
+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]
+
+  * add symlinks so icons are available for both sphinx and GH rendering
+  * optionally disable seat-timer by setting params to 00:00
+
+
+0.1.1 (2024-08-20)
 ------------------
 
 New
@@ -33,6 +60,8 @@ Changes
   Arnold]
 
   * revert the .keepdir bits and cleanup sphinx config and index
+  * update changelog and get ready for release version, cleanup
+    docs CI workflows
 - Still more readme updates and a docstring tweak. [Stephen L Arnold]
 - Try setting position and gravity options, cleanup entry window bits.
   [Stephen L Arnold]
@@ -59,6 +88,10 @@ Changes
 
 Fixes
 ~~~~~
+- Update doc deploy workflows per current deploy action docs. [Steve
+  Arnold]
+
+  * use permissions instead of the older github token setting
 - Even more docstring and readme/rst doc cleanup. [Stephen L Arnold]
 - Cleanup some oddball link anchors flagged by sphinx check. [Stephen L
   Arnold]

README.rst

@@ -349,7 +349,7 @@ as "time" strings, eg, the following sets an 8-hour max:
     day_max: "08:00"
 
 The seat timer can be disabled by setting both *max* and *snooze* to
-zeros, ie, set both values like so::
+zeros, ie, set both values like so:
 
 .. code-block:: yaml
 
@@ -372,11 +372,11 @@ tracking interval. The states and corresponding icons are shown below:
 :ERROR: |err| The state when either snooze period has expired.
 :APP: |app| While not a state, we use this to retrieve the app icon.
 
-.. |app| image:: images/timew.svg
-.. |inactive| image:: images/timew_inactive.svg
-.. |info| image:: images/timew_info.svg
-.. |warn| image:: images/timew_warning.svg
-.. |err| image:: images/timew_error.svg
+.. |app| image:: gh/images/timew.svg
+.. |inactive| image:: gh/images/timew_inactive.svg
+.. |info| image:: gh/images/timew_info.svg
+.. |warn| image:: gh/images/timew_warning.svg
+.. |err| image:: gh/images/timew_error.svg
 
 
 PyGObject references

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,27 +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',
 ]
 
+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/gh/images/timew.svg

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

docs/source/gh/images/timew_error.svg

@@ -0,0 +1 @@
+../../../../gh/images/timew_error.svg

docs/source/gh/images/timew_inactive.svg

@@ -0,0 +1 @@
+../../../../gh/images/timew_inactive.svg

docs/source/gh/images/timew_info.svg

@@ -0,0 +1 @@
+../../../../gh/images/timew_info.svg

docs/source/gh/images/timew_warning.svg

@@ -0,0 +1 @@
+../../../../gh/images/timew_warning.svg

docs/source/index.rst

@@ -11,19 +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::
-  :branch:
-  :commit:
-  :sha_length: 10
-  :uncommitted:
-  :untracked:
-
 .. toctree::
-  :maxdepth: 3
+  :maxdepth: 2
   :caption: Contents:
 
   README
-  modules
+  api/modules
   CHANGELOG
 
 Indices and tables