Merge pull request #18 from capn-freako/17-comment-clean-up-for-bette…

…r-sphinx-output Comments cleaned up for better Sphinx-generated documentation.
capn-freako · Nov 6, 2024 · 6e836b6 · 6e836b6
2 parents 4e468ac + 1768601
commit 6e836b6
Show file tree

Hide file tree

Showing 25 changed files with 627 additions and 1,008 deletions.
diff --git a/.gitignore b/.gitignore
@@ -27,6 +27,7 @@ share/python-wheels/
 MANIFEST
 *.whl
 *.gz
+.proj_ver
 
 # PyInstaller
 #  Usually these files are written by a python script from a template

diff --git a/Makefile b/Makefile
@@ -12,6 +12,7 @@ PROJ_FILE := pyproject.toml
 PROJ_INFO := src/PyChOpMarg.egg-info/PKG-INFO
 VER_FILE := .proj_ver
 VER_GETTER := ./get_proj_ver.py
+SHELL_EXEC := bash
 PYTHON_EXEC := python -I
 TOX_EXEC := tox
 TOX_SKIP_ENV := format
@@ -47,13 +48,13 @@ type-check:
 	${TOX_EXEC} run -e type-check
 
 docs: ${VER_FILE}
-	source $< && ${TOX_EXEC} run -e docs
+	${SHELL_EXEC} -c "source $<" && ${TOX_EXEC} run -e docs
 
 build: ${VER_FILE}
 	${TOX_EXEC} run -e build
 
 upload: ${VER_FILE}
-	source $< && ${TOX_EXEC} run -e upload
+	${SHELL_EXEC} -c "source $<" && ${TOX_EXEC} run -e upload
 
 test:
 	@for V in ${PYVERS}; do \
@@ -63,7 +64,7 @@ test:
 	done
 
 clean:
-	rm -rf .tox docs/build/ .mypy_cache .pytest_cache .venv
+	rm -rf .tox build/ dist/ docs/_build/ .mypy_cache .pytest_cache .venv
 
 help:
 	@echo "Available targets:"

diff --git a/PyChOpMarg_8023dj.ipynb b/PyChOpMarg_8023dj.ipynb
diff --git a/docs/GitHub_Clone.png b/docs/GitHub_Clone.png
diff --git a/docs/GitHub_Fork.png b/docs/GitHub_Fork.png
diff --git a/docs/com.rst b/docs/com.rst
@@ -1,14 +1,6 @@
 pychopmarg.com
 ==============
 
-Functions
----------
-
-.. autofunction:: pychopmarg.com.all_combs
-
-.. autofunction:: pychopmarg.com.calc_Hffe
-
-
 Classes
 ---------
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -9,7 +9,7 @@
 project = 'PyChOpMarg'
 copyright = '2024, David Banas'
 author = 'David Banas'
-release = 'v1.1.1'
+release = 'v2.1.2'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -35,11 +35,9 @@
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 autodoc_mock_imports = [
    "matplotlib",
-   "enable",
-   "chaco",
-   "traitsui"
 ]
 autodata_content = 'both'
+autodoc_member_order = 'bysource'
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

diff --git a/docs/develop.rst b/docs/develop.rst
@@ -0,0 +1,99 @@
+Developer Setup Guide
+=====================
+
+These instructions will help you get set up to make your own changes to the *PyChOpMarg* source code and see the effects of those changes immediately.
+
+It is generally advisable to work within a *virtual environment* when installing and/or developing a non-standard package, such as *PyChOpMarg*.
+And these instructions will guide you down that path.
+This will protect your existing system Python installation from any incompatibilities between it and *PyChOpMarg* and/or its dependencies.
+
+*GitHub* Repo. Forking/Cloning
+------------------------------
+
+In order to propagate any changes you make to the *PyChOpMarg* source code back into the main repository from which the official Python package is built, you must:
+
+1. Create your *fork* of the *PyChOpMarg* repo. under your own *GitHub* account.
+
+    a. Using your favorite browser, visit the [*PyChOpMarg* GitHub site](https://github.com/capn-freako/PyChOpMarg).
+
+    b. Create your own fork of the *PyChOpMarg* repo., by clicking on the *Fork* button:
+
+        .. image:: GitHub_Fork.png
+
+2. Clone your new fork to your preferred local development machine.
+
+    a. Copy the link to your new fork:
+
+        .. image:: GitHub_Clone.png
+
+    b. Move into the desired parent directory for your *PyChOpMarg* folder.
+
+    c. Execute the following command at an appropriate command/shell prompt:
+
+        ``git clone <Paste><RETURN>``
+
+Installation
+------------
+
+To install *PyChOpMarg* into a dedicated new virtual environment for development purposes, execute these commands from an appropriate shell prompt:
+
+1. ``python3 -m venv ~/.venv/pychopmarg-dev``
+
+    - This command creates the new dedicated Python virtual environment.
+
+    - I've assumed that you keep your Python virtual environments in the ``.venv/`` sub-directory of your home directory. If that's not the case then you'll need to modify the command slightly, to accommodate your system layout and usage habbits.
+
+2. ``source ~/.venv/pychopmarg-dev/bin/activate``
+
+    - This command activates the new virtual environment, so we can install packages into it.
+
+    - Windows users should use the command: ``. ~/.venv/pychopmarg-dev/Scripts/activate``
+
+    - You'll know that you have correctly activated your new virtual environment when you see the text "(pychopmarg-dev)" appear above your prompt.
+
+3. ``pushd PyChOpMarg/``
+
+    - Moving into the ``PyChOpMarg/`` directory is necessary, before executing the next command.
+
+4. ``pip install -e .``
+
+    - This command installs *PyChOpMarg* and its dependencies into your new virtual environment.
+
+    - While the dependencies are installed in the usual manner, *PyChOpMarg* is installed in "editable" mode.
+      This means that changes you make to the *PyChOpMarg* source code will have an immediate effect.
+
+5. Using the command: ``pip install <module>``, install the following <module>s:
+
+    - ``setuptools``
+    - ``tox``
+
+Develop & Test
+--------------
+
+Make your desired changes to the *PyChOpMarg* source code.
+Make sure to lint, flake, and type check your new code.
+The provided makefile can be used for all of this.
+Execute: ``make``, to see a list of available targets, along with descriptions.
+
+Contributing Your Improvements
+------------------------------
+
+In order to contribute your improvements to the main *PyChOpMarg* repository for inclusion in the next release, do the following:
+
+1. *Commit* your code changes to your local repo.
+
+    ``git commit``
+
+2. *Push* your new commit up to your fork on GitHub.
+
+    ``git push``
+
+Visit your fork on GitHub, using your favorite browser, and you will be offered the opportunity to create a *Pull Request* back to the main repo.
+By creating such a request, you are asking that your improvements be added to the main repo. and included in the next release.
+The development team will review your request and either:
+
+- accept it unmodified,
+
+- request that you make certain changes, or
+
+- realize that you are a numbskull and ask you to go away and never bother us again.
diff --git a/docs/index.rst b/docs/index.rst
@@ -6,13 +6,14 @@
 Welcome to PyChOpMarg's documentation!
 ======================================
 
-The *PyChOpMarg* package provides a Python implementation of COM, as per IEEE 802.3-22 Annex 93A.
+The *PyChOpMarg* package provides a Python implementation of COM, as per IEEE 802.3-22 Annex 93A/178A.
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
    quickstart
+   develop
    pychopmarg
    todo
 

diff --git a/docs/misc.rst b/docs/misc.rst
@@ -3,14 +3,6 @@ pychopmarg.<misc.>
 
 Miscellaneous modules in the *PyChOpMarg* package.
 
-utility
--------
-
-.. automodule:: pychopmarg.utility
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 cli
 ---
 
@@ -19,14 +11,6 @@ cli
    :undoc-members:
    :show-inheritance:
 
-view
-----
-
-.. automodule:: pychopmarg.view
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 common
 ------
 

diff --git a/docs/noise.rst b/docs/noise.rst
@@ -0,0 +1,10 @@
+pychopmarg.noise
+================
+
+Classes
+---------
+
+.. autoclass:: pychopmarg.noise.NoiseCalc
+   :members:
+   :undoc-members:
+   :no-inherited-members:
diff --git a/docs/optimize.rst b/docs/optimize.rst
@@ -0,0 +1,18 @@
+pychopmarg.optimize
+===================
+
+Classes
+---------
+
+.. autoclass:: pychopmarg.optimize.NormMode
+   :members:
+   :undoc-members:
+   :no-inherited-members:
+
+Functions
+---------
+
+.. autofunction:: pychopmarg.optimize.scale_taps
+.. autofunction:: pychopmarg.optimize.clip_taps
+.. autofunction:: pychopmarg.optimize.przf
+.. autofunction:: pychopmarg.optimize.mmse
diff --git a/docs/pychopmarg.rst b/docs/pychopmarg.rst
@@ -6,4 +6,9 @@
    :caption: Modules:
 
    com
-   misc
+   noise
+   optimize
+   utility
+
+**Note:** In addition to the above, see the ``pychopmarg.common`` module
+for useful abreviations used throughout the package.
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
@@ -11,25 +11,27 @@ Installation
 
 To install *PyChOpMarg* into a dedicated new virtual environment, execute these commands from an appropriate shell prompt:
 
-1. `python3 -m venv ~/.venv/pychopmarg`
+1. ``python3 -m venv ~/.venv/pychopmarg``
 
     - This command creates the new dedicated Python virtual environment.
 
-    * I've assumed that you keep your Python virtual environments in the `.venv/` sub-directory of your home directory. If that's not the case then you'll need to modify the command slightly, to accommodate your system layout and usage habbits.
+    - I've assumed that you keep your Python virtual environments in the ``.venv/`` sub-directory of your home directory. If that's not the case then you'll need to modify the command slightly, to accommodate your system layout and usage habbits.
 
-2. `source ~/.venv/pychopmarg/bin/activate`
+2. ``source ~/.venv/pychopmarg/bin/activate``
 
     - This command activates the new virtual environment, so we can install packages into it.
 
-    - Windows users should use the command: `. ~/.venv/pychopmarg/Scripts/activate`
+    - Windows users should use the command: ``. ~/.venv/pychopmarg/Scripts/activate``
 
     - You'll know that you have correctly activated your new virtual environment when you see the text "(pychopmarg)" appear above your prompt.
 
-3. `pip install pychopmarg`
+3. ``pip install pychopmarg``
 
     - This command installs *PyChOpMarg* and its dependencies into your new virtual environment.
 
 Launching the GUI
 -----------------
 
-To launch the *PyChOpMarg* GUI application, simply type: `pychopmarg` and hit `<RETURN>`.
+**Note:** The GUI is not currently working.
+
+To launch the *PyChOpMarg* GUI application, simply type: ``pychopmarg`` and hit ``<RETURN>``.
diff --git a/docs/utility.rst b/docs/utility.rst
@@ -0,0 +1,36 @@
+pychopmarg.utility
+==================
+
+**Note:** All submodule members are accessible, via: ``from pychopmarg.utility import ...``
+
+filter
+------
+
+.. automodule:: pychopmarg.utility.filter
+   :members:
+   :undoc-members:
+   :no-inherited-members:
+
+general
+-------
+
+.. automodule:: pychopmarg.utility.general
+   :members:
+   :undoc-members:
+   :no-inherited-members:
+
+probability
+-----------
+
+.. automodule:: pychopmarg.utility.probability
+   :members:
+   :undoc-members:
+   :no-inherited-members:
+
+sparams
+-------
+
+.. automodule:: pychopmarg.utility.sparams
+   :members:
+   :undoc-members:
+   :no-inherited-members:
diff --git a/pyproject.toml b/pyproject.toml
@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "PyChOpMarg"
 description = "Python implementation of COM, as per IEEE 802.3-22 Annex 93A/178A."
-version = "2.1.1"
+version = "2.1.2"
 authors = [{name = "David Banas", email = "capn.freako@gmail.com"}]
 urls = { documentation = "https://pychopmarg.readthedocs.io/en/latest/"}
 readme = "README.md"