Skip to content

Commit

Permalink
chg: doc: refactor doc extensions to use apidoc, add docs logo icon
Browse files Browse the repository at this point in the history
* cleanup more docstrings and sphinx modules

Signed-off-by: Stephen Arnold <[email protected]>
  • Loading branch information
sarnold committed Aug 26, 2024
1 parent ce666e1 commit b17102b
Show file tree
Hide file tree
Showing 9 changed files with 46 additions and 35 deletions.
34 changes: 27 additions & 7 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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"
Expand Down
1 change: 1 addition & 0 deletions docs/source/gh/images/timew.png
8 changes: 2 additions & 6 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 0 additions & 9 deletions docs/source/modules.rst

This file was deleted.

10 changes: 0 additions & 10 deletions docs/source/timew_status.rst

This file was deleted.

Binary file added gh/images/timew.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions setup.cfg
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ doc =
sphinx
sphinx_git
sphinx_rtd_theme
sphinxcontrib-apidoc
rst2pdf[svgsupport]
test =
pytest
Expand Down
15 changes: 13 additions & 2 deletions src/timew_status/utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand All @@ -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
Expand All @@ -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))

Expand All @@ -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)
Expand All @@ -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'
Expand Down Expand Up @@ -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
"""
Expand Down
3 changes: 2 additions & 1 deletion tox.ini
Original file line number Diff line number Diff line change
Expand Up @@ -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__'

0 comments on commit b17102b

Please sign in to comment.