diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 996f6ec..6c69c10 100644 --- a/CHANGELOG.rst +++ b/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] diff --git a/docs/source/conf.py b/docs/source/conf.py index 06201d1..52271ba 100644 --- a/docs/source/conf.py +++ b/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" diff --git a/docs/source/gh/images/timew.png b/docs/source/gh/images/timew.png new file mode 120000 index 0000000..25a3cb6 --- /dev/null +++ b/docs/source/gh/images/timew.png @@ -0,0 +1 @@ +../../../../gh/images/timew.png \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index f608a6e..367b54d 100644 --- a/docs/source/index.rst +++ b/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 diff --git a/docs/source/modules.rst b/docs/source/modules.rst deleted file mode 100644 index 43ecf55..0000000 --- a/docs/source/modules.rst +++ /dev/null @@ -1,9 +0,0 @@ -timew_status -============ - -Version: |version| - -.. toctree:: - :maxdepth: 4 - - timew_status diff --git a/docs/source/timew_status.rst b/docs/source/timew_status.rst deleted file mode 100644 index 7f9e138..0000000 --- a/docs/source/timew_status.rst +++ /dev/null @@ -1,10 +0,0 @@ -timew\_status package -===================== - -Module contents ---------------- - -.. automodule:: timew_status - :members: - :undoc-members: - :show-inheritance: diff --git a/gh/images/timew.png b/gh/images/timew.png new file mode 100644 index 0000000..47d16da Binary files /dev/null and b/gh/images/timew.png differ diff --git a/setup.cfg b/setup.cfg index df7d9ee..343dfcd 100644 --- a/setup.cfg +++ b/setup.cfg @@ -74,6 +74,7 @@ doc = sphinx sphinx_git sphinx_rtd_theme + sphinxcontrib-apidoc rst2pdf[svgsupport] test = pytest diff --git a/src/timew_status/utils.py b/src/timew_status/utils.py index b3377d0..2264a9e 100644 --- a/src/timew_status/utils.py +++ b/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 """ diff --git a/tox.ini b/tox.ini index 6739de1..13e43e1 100644 --- a/tox.ini +++ b/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__'