diff --git a/.github/workflows/_Checking_Pipeline.yml b/.github/workflows/_Checking_Pipeline.yml index 969536f..532297a 100644 --- a/.github/workflows/_Checking_Pipeline.yml +++ b/.github/workflows/_Checking_Pipeline.yml @@ -109,14 +109,6 @@ jobs: # with: # python_version: ${{ needs.UnitTestingParams.outputs.python_version }} - BuildTheDocs: - uses: pyTooling/Actions/.github/workflows/BuildTheDocs.yml@py313 - needs: - - UnitTestingParams -# - VerifyDocs - with: - artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_html }} - HTMLDocumentation: uses: pyTooling/Actions/.github/workflows/SphinxDocumentation.yml@py313 needs: @@ -144,7 +136,7 @@ jobs: needs: - UnitTestingParams - HTMLDocumentation - - PDFDocumentation +# - PDFDocumentation # - Coverage - PublishCoverageResults - StaticTypeCheck diff --git a/doc/JobTemplate/Parameters.rst b/doc/JobTemplate/Parameters.rst index 10c3bb7..bdaf3cf 100644 --- a/doc/JobTemplate/Parameters.rst +++ b/doc/JobTemplate/Parameters.rst @@ -138,7 +138,7 @@ python_version_list | Parameter Name | Required | Type | Default | +======================+==========+==========+============================+ | python_version_list | optional | string | ``3.8 3.9 3.10 3.11 3.12`` | -+----------------------+----------+----------+-------------------------- -+ ++----------------------+----------+----------+----------------------------+ Space separated list of CPython versions and/or mypy version to run tests with. diff --git a/doc/_static/css/override.css b/doc/_static/css/override.css new file mode 100644 index 0000000..27407d4 --- /dev/null +++ b/doc/_static/css/override.css @@ -0,0 +1,115 @@ +/* theme overrides */ +.rst-content h1, +.rst-content h2 { + margin-top: 24px; + margin-bottom: 6px; + text-decoration: underline; +} + +.rst-content h3, +.rst-content h4, +.rst-content h5, +.rst-content h6 { + margin-top: 12px; + margin-bottom: 6px; +} + +.rst-content p { + margin-bottom: 6px +} + +/* general overrides */ +html { + font-size: 15px; +} + +footer { + font-size: 95%; + text-align: center +} + +footer p { + margin-bottom: 0px /* 12px */; + font-size: 95% +} + +section > p, +.section p, +.simple li { + text-align: justify +} + +.rst-content .topic-title { + font-size: larger; + font-weight: 700; + margin-top: 18px; + margin-bottom: 6px; +} + +.rst-content p.rubric { + text-decoration: underline; + font-weight: 700; + margin-top: 18px; + margin-bottom: 16px; +} + +/* wyrm overrides */ +.wy-menu-vertical header, +.wy-menu-vertical p.caption { + color: #9b9b9b /* #55a5d9 */; + padding: 0 0.809em /* 0 1.618em */; + margin: 6px 0 0 0 /* 12px 0 0 */; + border-top: 1px solid #9b9b9b; +} + +.wy-side-nav-search { + margin-bottom: 0 /* .809em */; + background-color: #333333 /* #2980b9 */; + /* BTD: */ + /*color: #fcfcfc*/ +} + +.wy-side-nav-search input[type=text] { + border-radius: 0px /* 50px */; +} + +.wy-side-nav-search .wy-dropdown > a, .wy-side-nav-search > a { + /* BTD: */ + /*color: #fcfcfc;*/ + margin-bottom: 0.404em /* .809em */; +} + +.wy-side-nav-search > div.version { + margin: 0 0 6px 0; + /* BTD: */ + /*margin-top: -.4045em;*/ +} + +.wy-nav .wy-menu-vertical a:hover { + background-color: #333333 /* #2980b9 */; +} + +.wy-nav-content { + max-width: 1600px /* 800px */ ; +} + +.wy-nav-top { + background: #333333 /* #2980b9 */; +} + +/* Sphinx Design */ +.sd-tab-set { + margin: 0 +} + +.sd-tab-set > label { + padding-top: .5em; + padding-right: 1em; + padding-bottom: .5em; + padding-left: 1em +} + +.sd-container-fluid { + padding-left: 0; + padding-right: 0; +} diff --git a/doc/conf.py b/doc/conf.py index 1c3ddca..327b3ca 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -14,7 +14,7 @@ ROOT = Path(__file__).resolve().parent sys_path.insert(0, abspath(".")) sys_path.insert(0, abspath("..")) sys_path.insert(0, abspath("../pyDummy")) -sys_path.insert(0, abspath("_extensions")) +# sys_path.insert(0, abspath("_extensions")) # ============================================================================== @@ -23,9 +23,11 @@ sys_path.insert(0, abspath("_extensions")) # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. -project = "Actions" +githubNamespace = "pyTooling" +githubProject = "Actions" +project = "pyDummy" -packageInformationFile = Path(f"../pyDummy/__init__.py") +packageInformationFile = Path(f"../{project}/__init__.py") versionInformation = extractVersionInformation(packageInformationFile) author = versionInformation.Author @@ -73,30 +75,15 @@ except Exception as ex: # ============================================================================== # Options for HTML output # ============================================================================== -html_context = {} -ctx = ROOT / "context.json" -if ctx.is_file(): - html_context.update(loads(ctx.open('r').read())) - -if (ROOT / "_theme").is_dir(): - html_theme_path = ["."] - html_theme = "_theme" - html_theme_options = { - "logo_only": True, - "home_breadcrumbs": False, - "vcs_pageview_mode": 'blob', -# "body_max_width": None -# "navigation_depth": 5, - } -elif find_spec("sphinx_rtd_theme") is not None: - html_theme = "sphinx_rtd_theme" - html_theme_options = { - "logo_only": True, - "vcs_pageview_mode": 'blob', -# "navigation_depth": 5, - } -else: - html_theme = "alabaster" +html_theme = "sphinx_rtd_theme" +html_theme_options = { + "logo_only": True, + "vcs_pageview_mode": 'blob', + "navigation_depth": 5, +} +html_css_files = [ + 'css/override.css', +] # 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, @@ -107,7 +94,7 @@ html_logo = str(Path(html_static_path[0]) / "logo.png") html_favicon = str(Path(html_static_path[0]) / "icon.png") # Output file base name for HTML help builder. -htmlhelp_basename = "ActionsDoc" +htmlhelp_basename = f"{githubProject}Doc" # If not None, a 'Last updated on:' timestamp is inserted at every page # bottom, using the given strftime format. @@ -160,10 +147,10 @@ latex_elements = { # author, documentclass [howto, manual, or own class]). latex_documents = [ ( master_doc, - "Actions.tex", - "The pyTooling Actions Documentation", - "Patrick Lehmann", - "manual" + f"{githubProject}.tex", + f"The {githubProject} Documentation", + f"Patrick Lehmann", + f"manual" ), ] @@ -174,7 +161,6 @@ latex_documents = [ extensions = [ # Standard Sphinx extensions "sphinx.ext.autodoc", - "sphinx.ext.coverage", "sphinx.ext.extlinks", "sphinx.ext.intersphinx", "sphinx.ext.inheritance_diagram", @@ -186,9 +172,12 @@ extensions = [ # SphinxContrib extensions "sphinxcontrib.mermaid", # Other extensions + "sphinx_design", + "sphinx_copybutton", "sphinx_autodoc_typehints", - "sphinx_inline_tabs", "autoapi.sphinx", + "sphinx_reports", +# User defined extensions ] @@ -220,11 +209,11 @@ autodoc_typehints = "both" # Sphinx.Ext.ExtLinks # ============================================================================== extlinks = { - "gh": ("https://GitHub.com/%s", "gh:%s"), - "ghissue": ("https://GitHub.com/pyTooling/Actions/issues/%s", "issue #%s"), - "ghpull": ("https://GitHub.com/pyTooling/Actions/pull/%s", "pull request #%s"), - "ghsrc": ("https://GitHub.com/pyTooling/Actions/blob/main/%s", None), - "wiki": ("https://en.wikipedia.org/wiki/%s", None), + "gh": (f"https://GitHub.com/%s", "gh:%s"), + "ghissue": (f"https://GitHub.com/{githubNamespace}/{githubProject}/issues/%s", "issue #%s"), + "ghpull": (f"https://GitHub.com/{githubNamespace}/{githubProject}/pull/%s", "pull request #%s"), + "ghsrc": (f"https://GitHub.com/{githubNamespace}/{githubProject}/blob/main/%s", None), + "wiki": (f"https://en.wikipedia.org/wiki/%s", None), } @@ -264,18 +253,53 @@ todo_link_only = True # ============================================================================== -# Sphinx.Ext.Coverage +# sphinx-reports # ============================================================================== -coverage_show_missing_items = True +# report_unittest_testsuites = { +# "src": { +# "name": f"{project}", +# "xml_report": "../report/unit/unittest.xml", +# } +# } +# report_codecov_packages = { +# "src": { +# "name": f"{project}", +# "json_report": "../report/coverage/coverage.json", +# "fail_below": 80, +# "levels": "default" +# } +# } +# report_doccov_packages = { +# "src": { +# "name": f"{project}", +# "directory": f"../{project}", +# "fail_below": 80, +# "levels": "default" +# } +# } + + +# ============================================================================== +# Sphinx_Design +# ============================================================================== +# sd_fontawesome_latex = True # ============================================================================== # AutoAPI.Sphinx # ============================================================================== autoapi_modules = { - "pyDummy": { - "template": "module", - "output": "pyDummy", + f"{project}": { + "template": "package", + "output": project, "override": True } } + +for directory in [mod for mod in Path(f"../{project}").iterdir() if mod.is_dir() and mod.name != "__pycache__"]: + print(f"Adding module rule for '{project}.{directory.name}'") + autoapi_modules[f"{project}.{directory.name}"] = { + "template": "module", + "output": project, + "override": True + } diff --git a/doc/coverage/index.rst b/doc/coverage/index.rst index bad51b9..ef8d044 100644 --- a/doc/coverage/index.rst +++ b/doc/coverage/index.rst @@ -3,5 +3,5 @@ Code Coverage Report Code coverage report generated with `pytest `__ and `Coverage.py `__. -.. report:code-coverage:: +.. #report:code-coverage:: :packageid: src diff --git a/doc/requirements.txt b/doc/requirements.txt index e076084..efecb1e 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -6,6 +6,9 @@ pyTooling ~= 6.7 sphinx ~= 8.1 docutils ~= 0.21 +# ReadTheDocs Theme +sphinx_rtd_theme ~= 3.0 + # Sphinx Extenstions #sphinx.ext.coverage #sphinxcontrib-actdiag>=0.8.5 @@ -18,3 +21,6 @@ sphinx_design ~= 0.6.1 sphinx-copybutton >= 0.5.2 sphinx_autodoc_typehints ~= 2.5 # changelog>=0.3.5 +sphinx_reports ~= 0.6 + +# BuildTheDocs Extensions (mostly patched Sphinx extensions) diff --git a/doc/shields.inc b/doc/shields.inc index 039867c..08ea106 100644 --- a/doc/shields.inc +++ b/doc/shields.inc @@ -7,11 +7,11 @@ .. |SHIELD:svg:pyTooling-github| image:: https://img.shields.io/badge/pyTooling-Actions-63bf7f.svg?longCache=true&style=flat-square&longCache=true&logo=GitHub :alt: Sourcecode on GitHub :height: 22 - :target: https://GitHub.com/pyTooling/pyTooling + :target: https://GitHub.com/pyTooling/Actions .. |SHIELD:png:pyTooling-github| image:: https://raster.shields.io/badge/pyTooling-Actions-63bf7f.svg?longCache=true&style=flat-square&longCache=true&logo=GitHub :alt: Sourcecode on GitHub :height: 22 - :target: https://GitHub.com/pyTooling/pyTooling + :target: https://GitHub.com/pyTooling/Actions .. # Sourcecode license .. |SHIELD:svg:pyTooling-src-license| image:: https://img.shields.io/pypi/l/pyTooling?longCache=true&style=flat-square&logo=Apache&label=code diff --git a/doc/unittests/index.rst b/doc/unittests/index.rst index 8b840ee..f965014 100644 --- a/doc/unittests/index.rst +++ b/doc/unittests/index.rst @@ -3,5 +3,5 @@ Unittest Summary Report Unittest report generated with `pytest `__. -.. report:unittest-summary:: +.. #report:unittest-summary:: :reportid: src