Skip to content

Commit

Permalink
Updated documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
@Paebbels
Paebbels committed Jan 20, 2024
1 parent a0ddc2c commit 4559127
Show file tree
Hide file tree
Showing 10 changed files with 428 additions and 86 deletions.
4 changes: 2 additions & 2 deletions doc/Dependency.rst
View file
Expand Up @@ -23,7 +23,7 @@ pyVHDLModel Package
+--------------------------------------------------------+-------------+------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
| **Package** | **Version** | **License** | **Dependencies** |
+========================================================+=============+==========================================================================================+=================================================================================================================================+
| `pyTooling <https://GitHub.com/pyTooling/pyTooling>`__ | ≥5.0.0 | `Apache License, 2.0 <https://GitHub.com/pyTooling/pyTooling/blob/master/LICENSE.txt>`__ | *None* |
| `pyTooling <https://GitHub.com/pyTooling/pyTooling>`__ | ≥6.0.0 | `Apache License, 2.0 <https://GitHub.com/pyTooling/pyTooling/blob/master/LICENSE.txt>`__ | *None* |
+--------------------------------------------------------+-------------+------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+


Expand Down Expand Up @@ -127,7 +127,7 @@ install the mandatory dependencies too.
+----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Package** | **Version** | **License** | **Dependencies** |
+============================================================================+==============+==========================================================================================================+======================================================================================================================================================+
| `pyTooling <https://GitHub.com/pyTooling/pyTooling>`__ | ≥5.0.0 | `Apache License, 2.0 <https://GitHub.com/pyTooling/pyTooling/blob/main/LICENSE.md>`__ | *None* |
| `pyTooling <https://GitHub.com/pyTooling/pyTooling>`__ | ≥6.0.0 | `Apache License, 2.0 <https://GitHub.com/pyTooling/pyTooling/blob/main/LICENSE.md>`__ | *None* |
+----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| `wheel <https://GitHub.com/pypa/wheel>`__ | ≥0.40.0 | `MIT <https://github.com/pypa/wheel/blob/main/LICENSE.txt>`__ | *Not yet evaluated.* |
+----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
Expand Down
7 changes: 7 additions & 0 deletions doc/DocCoverage.rst
View file
@@ -0,0 +1,7 @@
Documentation Coverage
######################

Documentation coverage generated by `docstr-coverage <https://github.com/HunterMcGushion/docstr_coverage>`__.

.. report:doc-coverage::
:packageid: src
204 changes: 188 additions & 16 deletions doc/Installation.rst
View file
@@ -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 <DEP/packaging>` are installed.

.. tab-set::

.. tab-item:: Linux/MacOS
:sync: Linux

.. code-block:: bash
cd <sphinx-reports>
# 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 <sphinx-reports>
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
101 changes: 101 additions & 0 deletions doc/_static/css/override.css
View file
@@ -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;
}

0 comments on commit 4559127

Please sign in to comment.