From a33d6b82f276d0573b2fdee8ad2df1f5d2207fbe Mon Sep 17 00:00:00 2001 From: Stephen Arnold Date: Sun, 25 Aug 2024 17:47:11 -0700 Subject: [PATCH] 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 --- CHANGELOG.rst | 9 +++++++++ docs/source/conf.py | 34 +++++++++++++++++++++++++------- docs/source/gh/images/timew.png | 1 + docs/source/index.rst | 8 ++------ docs/source/modules.rst | 9 --------- docs/source/timew_status.rst | 10 ---------- gh/images/timew.png | Bin 0 -> 1836 bytes setup.cfg | 1 + src/timew_status/utils.py | 15 ++++++++++++-- tox.ini | 3 ++- 10 files changed, 55 insertions(+), 35 deletions(-) create mode 120000 docs/source/gh/images/timew.png delete mode 100644 docs/source/modules.rst delete mode 100644 docs/source/timew_status.rst create mode 100644 gh/images/timew.png 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 0000000000000000000000000000000000000000..47d16daac5f3ed409704f7a3e0c6dff829883b19 GIT binary patch literal 1836 zcmX|BX*3(?8V;_dYN=XFhuCUTBG#t%8c|!RqPA;kL`W)IlOU2cz(7B7wuI^z<@OUhV@cmH+hp#{Di~B0! z2)ZX0+rwKC4z&Fx`tX(7=Wp{g>-CoRg>|52ErCm6W`a^1I9lUjdsq0vMc#g+ ztyGD&rOM*KY74_*F`k!Bds%8xmnAf4sr(`?=-{BFFCtY`WdA6Q)_yMU(3nk~5@a9y`|`9dwOZ$pxP)Li*hldDz4&T3d5DtrR9_GuN1 zo=wXQBBjYTy6SwCcrJOA>5<<@cdc`!Y^MwbXY4Ab?5N9!3dNzAFLlt~mzebTpo++M zD$#l4E5SiZjgvh2GM-!7HYI#mNhqLN{;ctzgU_5nH(Q%0e_Z%dfsKk~o?m?^m+um6 zG)r!8((N=E`)@F)Vd0DwM0W36m!e)i2Zebgo%G$I?Kf7bBAl5ujIevxe;C;FY^!qz zeW#sw;O#H43Eya~ry#V86O(-*YWprqwcS&FMumVR>pcmIRM3cgv8SKX+|{hl8H%&i z-zuT1UnNlAOb9z^mWw;F4NJo+%LzF5$ox&eKXFj3y> z`u5&03x&pvlnFYkK-r=>YS;LF^7@y0u7ylf0iCybsqW@P7)GA=oD;85ohD#vB9W5v zyMNJ^n6*V;cZCM_`dpM2&b>BgMpedc5v9ni&(WPwpQsL8rS2+ z6_n1%9QA1X$1E%pI~ez?=8Xqz)sFQg;laHSctOAdH+}@Pq&1<*TCy@935!>`b5M#$ zJrD;4rb9ph2{$RHXXwzUmIW4}hYweh?`n?1X_qyAFoPGMbKv=i`O}YQ3S-bJ@HDx6X=bv)t*UJ*y29=yv$rjwYtxme)^OxWTH1C^4KnHMo;! zQ`UMFT)1_;u$WutJ)CRi5BAMpeT=T8t&Qxz9AM8!f5B~ac~eV2O=@h|luLmQn4APZ Q{{IeevUh{k|8gtwf39s|y#N3J literal 0 HcmV?d00001 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__'