diff --git a/doc/Dependency.rst b/doc/Dependency.rst index fdb1e9f9e..c08fa8daf 100644 --- a/doc/Dependency.rst +++ b/doc/Dependency.rst @@ -23,7 +23,7 @@ pyVHDLModel Package +--------------------------------------------------------+-------------+------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+ | **Package** | **Version** | **License** | **Dependencies** | +========================================================+=============+==========================================================================================+=================================================================================================================================+ -| `pyTooling `__ | ≥5.0.0 | `Apache License, 2.0 `__ | *None* | +| `pyTooling `__ | ≥6.0.0 | `Apache License, 2.0 `__ | *None* | +--------------------------------------------------------+-------------+------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+ @@ -127,7 +127,7 @@ install the mandatory dependencies too. +----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Package** | **Version** | **License** | **Dependencies** | +============================================================================+==============+==========================================================================================================+======================================================================================================================================================+ -| `pyTooling `__ | ≥5.0.0 | `Apache License, 2.0 `__ | *None* | +| `pyTooling `__ | ≥6.0.0 | `Apache License, 2.0 `__ | *None* | +----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | `wheel `__ | ≥0.40.0 | `MIT `__ | *Not yet evaluated.* | +----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/doc/DocCoverage.rst b/doc/DocCoverage.rst new file mode 100644 index 000000000..c1e75266a --- /dev/null +++ b/doc/DocCoverage.rst @@ -0,0 +1,7 @@ +Documentation Coverage +###################### + +Documentation coverage generated by `docstr-coverage `__. + +.. report:doc-coverage:: + :packageid: src diff --git a/doc/Installation.rst b/doc/Installation.rst index 9693bba4d..19d04855e 100644 --- a/doc/Installation.rst +++ b/doc/Installation.rst @@ -1,37 +1,209 @@ -.. _installation: +.. _INSTALL: Installation/Updates #################### +.. _INSTALL/pip: +Using PIP to Install from PyPI +****************************** -.. _installation-pip: +The following instruction are using PIP (Package Installer for Python) as a package manager and PyPI (Python Package +Index) as a source of Python packages. -Using PIP -********* -Installation using PIP -====================== +.. _INSTALL/pip/install: + +Installing a Wheel Package from PyPI using PIP +============================================== + +Users of pyTooling can select if the want to install a basic variant of pyTooling. See :ref:`DEP` for more +details. + +.. tab-set:: + + .. tab-item:: Linux/MacOS + :sync: Linux + + .. code-block:: bash + + # Basic sphinx-reports package + pip3 install pyVHDLModel + + .. tab-item:: Windows + :sync: Windows + + .. code-block:: powershell + + # Basic sphinx-reports package + pip install pyVHDLModel + +Developers can install further dependencies for documentation generation (``doc``) or running unit tests (``test``) or +just all (``all``) dependencies. + +.. tab-set:: + + .. tab-item:: Linux/MacOS + :sync: Linux + + .. tab-set:: + + .. tab-item:: With Documentation Dependencies + :sync: Doc + + .. code-block:: bash + + # Install with dependencies to generate documentation + pip3 install pyVHDLModel[doc] + + .. tab-item:: With Unit Testing Dependencies + :sync: Unit + + .. code-block:: bash + + # Install with dependencies to run unit tests + pip3 install pyVHDLModel[test] + + .. tab-item:: All Developer Dependencies + :sync: All + + .. code-block:: bash + + # Install with all developer dependencies + pip install pyVHDLModel[all] + + .. tab-item:: Windows + :sync: Windows + + .. tab-set:: + + .. tab-item:: With Documentation Dependencies + :sync: Doc + + .. code-block:: powershell + + # Install with dependencies to generate documentation + pip install pyVHDLModel[doc] + + .. tab-item:: With Unit Testing Dependencies + :sync: Unit + + .. code-block:: powershell + + # Install with dependencies to run unit tests + pip install pyVHDLModel[test] + + .. tab-item:: All Developer Dependencies + :sync: All + + .. code-block:: powershell + + # Install with all developer dependencies + pip install pyVHDLModel[all] -.. code-block:: bash - pip3 install pyVHDLModel +.. _INSTALL/pip/update: +Updating from PyPI using PIP +============================ -Updating using PIP -================== +.. tab-set:: + + .. tab-item:: Linux/MacOS + :sync: Linux + + .. code-block:: bash + + pip install -U pyVHDLModel + + .. tab-item:: Windows + :sync: Windows + + .. code-block:: powershell + + pip3 install -U pyVHDLModel + + +.. _INSTALL/pip/uninstall: + +Uninstallation using PIP +======================== + +.. tab-set:: + + .. tab-item:: Linux/MacOS + :sync: Linux + + .. code-block:: bash + + pip uninstall pyVHDLModel + + .. tab-item:: Windows + :sync: Windows + + .. code-block:: powershell + + pip3 uninstall pyVHDLModel + + +.. _INSTALL/setup: + +Using ``setup.py`` (legacy) +*************************** + +See sections above on how to use PIP. + +Installation using ``setup.py`` +=============================== .. code-block:: bash - pip3 install -U pyVHDLModel + setup.py install + + +.. _INSTALL/building: + +Local Packaging and Installation via PIP +**************************************** + +For development and bug fixing it might be handy to create a local wheel package and also install it locally on the +development machine. The following instructions will create a local wheel package (``*.whl``) and then use PIP to +install it. As a user might have a sphinx-reports installation from PyPI, it's recommended to uninstall any previous +sphinx-reports packages. (This step is also needed if installing an updated local wheel file with same version number. PIP +will not detect a new version and thus not overwrite/reinstall the updated package contents.) + +Ensure :ref:`packaging requirements ` are installed. + +.. tab-set:: + + .. tab-item:: Linux/MacOS + :sync: Linux + + .. code-block:: bash + + cd + + # Package the code in a wheel (*.whl) + python -m build --wheel + + # Uninstall the old package + python -m pip uninstall -y pyVHDLModel + + # Install from wheel + python -m pip install ./dist/pyVHDLModel-0.28.0-py3-none-any.whl + .. tab-item:: Windows + :sync: Windows + .. code-block:: powershell -.. _installation-setup: + cd -Using setup.py -************** + # Package the code in a wheel (*.whl) + py -m build --wheel -.. todo:: + # Uninstall the old package + py -m pip uninstall -y pyVHDLModel - Describe setup procedure using ``setup.py`` + # Install from wheel + py -m pip install .\dist\pyVHDLModel-0.28.0-py3-none-any.whl diff --git a/doc/_static/css/override.css b/doc/_static/css/override.css new file mode 100644 index 000000000..5f36fec2f --- /dev/null +++ b/doc/_static/css/override.css @@ -0,0 +1,101 @@ +/* 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 +} + +/* 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 9f75be6e7..1ea25c4ad 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -2,18 +2,19 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. from importlib.util import find_spec -from json import loads +from sys import path as sys_path from os.path import abspath from pathlib import Path -from sys import path as sys_path +from json import loads from pyTooling.Packaging import extractVersionInformation ROOT = Path(__file__).resolve().parent -sys_path.insert(0, abspath('.')) -sys_path.insert(0, abspath('..')) -sys_path.insert(0, abspath('../pyVHDLModel')) +sys_path.insert(0, abspath(".")) +sys_path.insert(0, abspath("..")) +sys_path.insert(0, abspath("../pyVHDLModel")) +# sys_path.insert(0, abspath("_extensions")) # ============================================================================== @@ -22,7 +23,7 @@ # 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 = "pyVHDLModel" +project = "pyVHDLModel" packageInformationFile = Path(f"../{project.replace('.', '/')}/__init__.py") versionInformation = extractVersionInformation(packageInformationFile) @@ -77,43 +78,35 @@ 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" +# ============================================================================== +# Options for HTML output +# ============================================================================== +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, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ["_static"] html_logo = str(Path(html_static_path[0]) / "logo.svg") html_favicon = str(Path(html_static_path[0]) / "favicon.svg") # Output file base name for HTML help builder. -htmlhelp_basename = 'pyVHDLModelDoc' +htmlhelp_basename = "pyVHDLModelDoc" # If not None, a 'Last updated on:' timestamp is inserted at every page # bottom, using the given strftime format. # The empty string is equivalent to '%b %d, %Y'. html_last_updated_fmt = "%d.%m.%Y" - # ============================================================================== # Python settings # ============================================================================== @@ -128,13 +121,13 @@ latex_elements = { # The paper size ('letterpaper' or 'a4paper'). - 'papersize': 'a4paper', + "papersize": "a4paper", # The font size ('10pt', '11pt' or '12pt'). #'pointsize': '10pt', # Additional stuff for the LaTeX preamble. - 'preamble': dedent(r""" + "preamble": dedent(r""" % ================================================================================ % User defined additional preamble code % ================================================================================ @@ -160,10 +153,10 @@ # author, documentclass [howto, manual, or own class]). latex_documents = [ ( master_doc, - 'pyVHDLModel.tex', - 'The pyVHDLModel Documentation', - 'Patrick Lehmann', - 'manual' + "pyVHDLModel.tex", + "The pyVHDLModel Documentation", + "Patrick Lehmann", + "manual" ), ] @@ -174,7 +167,6 @@ extensions = [ # Standard Sphinx extensions "sphinx.ext.autodoc", - "sphinx.ext.coverage", "sphinx.ext.extlinks", "sphinx.ext.intersphinx", "sphinx.ext.inheritance_diagram", @@ -186,9 +178,12 @@ # SphinxContrib extensions "sphinxcontrib.mermaid", # Other extensions - "sphinx_fontawesome", + "sphinx_design", + "sphinx_copybutton", "sphinx_autodoc_typehints", "autoapi.sphinx", + "sphinx_reports", +# User defined extensions ] @@ -196,10 +191,10 @@ # Sphinx.Ext.InterSphinx # ============================================================================== intersphinx_mapping = { - 'python': ('https://docs.python.org/3', None), - 'vasg': ('https://IEEE-P1076.gitlab.io/', None), - 'pyTool': ('https://pyTooling.github.io/pyTooling/', None), - 'ghdl': ('https://GHDL.github.io/ghdl/', None), + "python": ("https://docs.python.org/3", None), + "vasg": ("https://IEEE-P1076.gitlab.io/", None), + "pyTool": ("https://pyTooling.github.io/pyTooling/", None), + "ghdl": ("https://GHDL.github.io/ghdl/", None), } @@ -213,7 +208,7 @@ # "inherited-members": True, # "exclude-members": "__weakref__" #} -autodoc_class_signature = "separated" +#autodoc_class_signature = "separated" autodoc_member_order = "bysource" # alphabetical, groupwise, bysource autodoc_typehints = "both" #autoclass_content = "both" @@ -223,9 +218,11 @@ # Sphinx.Ext.ExtLinks # ============================================================================== extlinks = { - "ghissue": ('https://GitHub.com/vhdl/pyVHDLModel/issues/%s', 'issue #%s'), - "ghpull": ('https://GitHub.com/vhdl/pyVHDLModel/pull/%s', 'pull request #%s'), - "ghsrc": ('https://GitHub.com/vhdl/pyVHDLModel/blob/main/%s?ts=2', None), + "gh": ("https://GitHub.com/%s", "gh:%s"), + "ghissue": ("https://GitHub.com/VHDL/pyVHDLModel/issues/%s", "issue #%s"), + "ghpull": ("https://GitHub.com/VHDL/pyVHDLModel/pull/%s", "pull request #%s"), + "ghsrc": ("https://GitHub.com/VHDL/pyVHDLModel/blob/main/%s", None), + "wiki": ("https://en.wikipedia.org/wiki/%s", None), } @@ -265,14 +262,70 @@ # ============================================================================== -# Sphinx.Ext.Coverage +# Sphinx-reports # ============================================================================== -coverage_show_missing_items = True +report_dep_dependencies = { + "src": ["../requirements.txt"], + "doc": ["requirements.txt"], + "unit": ["../tests/unit/requirements.txt"], + "build": ["../build/requirements.txt"], + "publish": ["../dist/requirements.txt"], +} + +_coverageLevels = { + 30: {"class": "report-cov-below30", "desc": "almost undocumented"}, + 50: {"class": "report-cov-below50", "desc": "poorly documented"}, + 80: {"class": "report-cov-below80", "desc": "roughly documented"}, + 90: {"class": "report-cov-below90", "desc": "well documented"}, + 100: {"class": "report-cov-below100", "desc": "excellent documented"}, + "error": {"class": "report-cov-error", "desc": "internal error"}, +} + +report_unittest_testsuites = { + "src": {"xml_report": "../report/unit/unittest.xml"}, + "example-junit-basic": {"xml_report": "../tests/data/unittest/junit-basic.xml"}, + "example-junit-complete": {"xml_report": "../tests/data/unittest/junit-complete.xml"}, + "example-osvvm": {"xml_report": "../tests/data/unittest/osvvm-Libraries.xml"} +} +report_codecov_packages = { + "src": { + "name": "pyVHDLModel", + "json_report": "../report/coverage/coverage.json", + "fail_below": 80, + "levels": _coverageLevels + } +} +report_doccov_packages = { + "src": { + "name": "pyVHDLModel", + "directory": "../pyVHDLModel", + "fail_below": 80, + "levels": _coverageLevels + } +} + + +# ============================================================================== +# Sphinx_Design +# ============================================================================== +sd_fontawesome_latex = True # ============================================================================== # AutoAPI.Sphinx # ============================================================================== autoapi_modules = { - 'pyVHDLModel': {'output': "pyVHDLModel", "override": True} + project: { + "template": "module", + "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 80bbad2e9..bad51b90a 100644 --- a/doc/coverage/index.rst +++ b/doc/coverage/index.rst @@ -1,4 +1,7 @@ -Coverage Report -############### +Code Coverage Report +#################### -*Placeholder for the Coverage report generated with* ``pytest`` *and* ``coverage``. +Code coverage report generated with `pytest `__ and `Coverage.py `__. + +.. report:code-coverage:: + :packageid: src diff --git a/doc/index.rst b/doc/index.rst index c6364fb39..499a5bf7f 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -192,9 +192,6 @@ License This Python package (source code) is licensed under **Apache License 2.0**. |br| The accompanying documentation is licensed under **Creative Commons - Attribution 4.0 (CC-BY 4.0)**. ------------------------------------- - -.. |docdate| date:: %d.%b %Y - %H:%M .. only:: html @@ -237,9 +234,10 @@ License :caption: References and Reports :hidden: - pyVHDLModel/pyVHDLModel - Unittest Report ➚ - Coverage Report ➚ + Python Class Reference + unittests/index + coverage/index + Doc. Coverage Report Static Type Check Report ➚ @@ -257,3 +255,4 @@ License Glossary genindex Python Module Index + TODO diff --git a/doc/requirements.txt b/doc/requirements.txt index 73d902076..9966ac9d4 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,20 +1,25 @@ -r ../requirements.txt -pyTooling >= 5.0.0, <6.0 +pyTooling ~= 6.0 # Enforce latest version on ReadTheDocs -Sphinx >= 7.1.0, <8.0 +sphinx >= 7.2, < 8.0 +docutils >= 0.18.0, < 0.19.0 + +# ReadTheDocs Theme +sphinx_rtd_theme ~= 2.0.0 # Sphinx Extenstions -#sphinx.ext.coverage #sphinxcontrib-actdiag>=0.8.5 -sphinxcontrib-mermaid>=0.9.2 +sphinxcontrib-mermaid >= 0.9.2 #sphinxcontrib-seqdiag>=0.8.5 #sphinxcontrib-textstyle>=0.2.1 #sphinxcontrib-spelling>=2.2.0 -autoapi>=2.0.1 -sphinx_fontawesome >= 0.0.6 -sphinx_autodoc_typehints >= 1.24.0 +autoapi >= 2.0.1 +sphinx_design >= 0.5.0 +sphinx-copybutton >= 0.5.2 +sphinx_autodoc_typehints >= 1.25.2 +sphinx_reports ~= 0.5 # changelog>=0.3.5 # BuildTheDocs Extensions (mostly patched Sphinx extensions) diff --git a/doc/unittests/index.rst b/doc/unittests/index.rst index dd6de5e77..8b840ee66 100644 --- a/doc/unittests/index.rst +++ b/doc/unittests/index.rst @@ -1,4 +1,7 @@ -UnitTest Report -############### +Unittest Summary Report +####################### -*Placeholder for the unittest report generated with* ``pytest``. +Unittest report generated with `pytest `__. + +.. report:unittest-summary:: + :reportid: src diff --git a/setup.py b/setup.py index 51f1f8d07..f92048ddc 100644 --- a/setup.py +++ b/setup.py @@ -30,6 +30,8 @@ # ==================================================================================================================== # # """Package installer for 'An abstract VHDL language model'.""" +from setuptools import setup + from pathlib import Path from pyTooling.Packaging import DescribePythonPackageHostedOnGitHub, DEFAULT_CLASSIFIERS @@ -38,7 +40,7 @@ packageDirectory = packageName packageInformationFile = Path(f"{packageDirectory}/__init__.py") -DescribePythonPackageHostedOnGitHub( +setup(**DescribePythonPackageHostedOnGitHub( packageName=packageName, description="An abstract VHDL language model.", gitHubNamespace=gitHubNamespace, @@ -53,4 +55,4 @@ dataFiles={ packageName: ["py.typed"] } -) +))