From 1d4961d0957af7672a17a32e4cf512972054eb77 Mon Sep 17 00:00:00 2001 From: Sanhe Date: Sat, 26 Mar 2022 23:24:41 -0400 Subject: [PATCH] upgrade doc site --- docs/source/conf.py | 44 +++++++++++++++------------ docs/source/index.rst | 4 +++ docs/source/pathlib_mate/__init__.rst | 16 +++++----- docs/source/pathlib_mate/_version.rst | 5 +++ docs/source/pathlib_mate/winzip.rst | 5 --- pathlib_mate/helper.py | 4 +-- requirements-doc.txt | 23 +++++++------- 7 files changed, 54 insertions(+), 47 deletions(-) create mode 100644 docs/source/pathlib_mate/_version.rst delete mode 100644 docs/source/pathlib_mate/winzip.rst diff --git a/docs/source/conf.py b/docs/source/conf.py index ab7bad7..3cc0a6c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -45,6 +45,7 @@ 'sphinx.ext.viewcode', 'sphinxcontrib.jinja', 'sphinx_copybutton', + 'sphinx_inline_tabs', 'docfly.directives', ] @@ -87,7 +88,7 @@ exclude_patterns = [] # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = 'monokai' # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True @@ -97,35 +98,43 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'alabaster' +html_theme = "furo" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -# -# html_theme_options = {} +html_theme_options = { + "sidebar_hide_name": False, +} +pygments_dark_style = "monokai" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] -html_logo = "./_static/pathlib_mate-logo.png" -html_favicon = "./_static/pathlib_mate-favicon.ico" +html_css_files = [ + 'css/custom-style.css', +] +html_js_files = [ + 'js/sorttable.js', +] +html_logo = "./_static/{}-logo.png".format(pathlib_mate.__name__) +html_favicon = "./_static/{}-favicon.ico".format(pathlib_mate.__name__) # Custom sidebar templates, must be a dictionary that maps document names # to template names. # # This is required for the alabaster theme # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars -html_sidebars = { - '**': [ - 'about.html', - 'navigation.html', - 'relations.html', # needs 'show_related': True theme option to display - 'searchbox.html', - 'donate.html', - ] -} +# html_sidebars = { +# '**': [ +# 'about.html', +# 'navigation.html', +# 'relations.html', # needs 'show_related': True theme option to display +# 'searchbox.html', +# 'donate.html', +# ] +# } # -- Options for HTMLHelp output ------------------------------------------ @@ -207,8 +216,3 @@ "%s.tests" % package_name, ] ).fly() - - -def setup(app): - app.add_stylesheet('css/custom-style.css') - app.add_javascript('js/sorttable.js') diff --git a/docs/source/index.rst b/docs/source/index.rst index 504a414..4663e0b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,4 +1,8 @@ .. contents:: + :class: this-will-duplicate-information-and-it-is-still-useful-here + :depth: 1 + :local: + Release v\ |release| (:ref:`What's new? `). diff --git a/docs/source/pathlib_mate/__init__.rst b/docs/source/pathlib_mate/__init__.rst index d03bfeb..dc06150 100644 --- a/docs/source/pathlib_mate/__init__.rst +++ b/docs/source/pathlib_mate/__init__.rst @@ -10,15 +10,15 @@ sub packages and modules .. toctree:: :maxdepth: 1 - mate_path_filters - mate_tool_box_zip - mate_mutate_methods + _version <_version> + hashes + helper mate_attr_accessor - mate_tool_box mate_hashes_methods - str_encode - winzip + mate_mutate_methods + mate_path_filters + mate_tool_box + mate_tool_box_zip pathlib2 - helper - hashes + str_encode \ No newline at end of file diff --git a/docs/source/pathlib_mate/_version.rst b/docs/source/pathlib_mate/_version.rst new file mode 100644 index 0000000..a0c8009 --- /dev/null +++ b/docs/source/pathlib_mate/_version.rst @@ -0,0 +1,5 @@ +_version +======== + +.. automodule:: pathlib_mate._version + :members: \ No newline at end of file diff --git a/docs/source/pathlib_mate/winzip.rst b/docs/source/pathlib_mate/winzip.rst deleted file mode 100644 index 8f65fbd..0000000 --- a/docs/source/pathlib_mate/winzip.rst +++ /dev/null @@ -1,5 +0,0 @@ -winzip -====== - -.. automodule:: pathlib_mate.winzip - :members: \ No newline at end of file diff --git a/pathlib_mate/helper.py b/pathlib_mate/helper.py index 2bb1b29..062a415 100644 --- a/pathlib_mate/helper.py +++ b/pathlib_mate/helper.py @@ -43,8 +43,8 @@ def ensure_list(path_or_path_list): def repr_data_size( - size_in_bytes: int, - precision: int = 2, + size_in_bytes, + precision=2, ): """ Return human readable string represent of a file size. Doesn't support diff --git a/requirements-doc.txt b/requirements-doc.txt index 487e179..0d512d5 100644 --- a/requirements-doc.txt +++ b/requirements-doc.txt @@ -1,16 +1,15 @@ -sphinx==1.8.1 - -# Theme - -sphinx_rtd_theme +# This requirements file should only include dependencies for documentations +# sphinx doc builder +sphinx==4.3.0 # Extensions +sphinx-inline-tabs==2021.8.17b10 # allow inline tab +sphinx-jinja==1.1.1 # allow jinja2 template +sphinx-copybutton==0.4.0 # add copy to clipboard button for code block +rstobj==0.0.7 # generate list table from data -sphinx-jinja # allow jinja2 template -sphinx-copybutton # add copy to clipboard button for code block -docfly>=0.0.17 # auto API manual, auto Table of Content -rstobj>=0.0.5 # generate list table from data +# docfly # auto API manual, auto Table of Content +docfly==1.0.2 # sphinx-doc automation -# Other - -pygments # live RestructuredText preview +# Theme +furo==2021.8.31 # modern doc theme