Merge branch 'tutorial-enhancements' into daniel/git_actions_py_version

Author: betaBison

.github/workflows/build.yml

@@ -85,7 +85,7 @@ jobs:
 
       - name: Get changed files since last remote commit
         id: changed-files
-        uses: tj-actions/changed-files@v34
+        uses: tj-actions/changed-files@v41
 
       - name: Check if index.rst changed when README.md file changes
         if: contains(steps.changed-files.outputs.modified_files, 'README.md') && !contains(steps.changed-files.outputs.modified_files, 'docs/source/index.rst')

README.md

@@ -9,25 +9,31 @@ gnss_lib_py
 `gnss_lib_py` is a modular Python tool for parsing, analyzing, and
 visualizing Global Navigation Satellite Systems (GNSS) data and state
 estimates.
-It also provides an intuitive and modular framework allowing users to
+It also provides an intuitive and modular framework which allows users to
 quickly prototype, implement, and visualize GNSS algorithms.
 `gnss_lib_py` is modular in the sense that multiple types of
-algorithms can be easily exchanged for each other and extendable in
-facilitating user-specific extensions of existing implementations.
+algorithms or datasets can be easily exchanged for each other.
+It is extendable in facilitating user-specific extensions of existing
+implementations.
 
-<img src="https://raw.githubusercontent.com/Stanford-NavLab/gnss_lib_py/main/docs/source/img/skyplot.png" alt="satellite skyplot" width="600"/>
+<img src="https://raw.githubusercontent.com/Stanford-NavLab/gnss_lib_py/main/docs/source/img/skyplot.png" alt="Skyplot of GNSS satellite movement over time" width="600"/>
 
 `gnss_lib_py` contains parsers for common file types used for
 storing GNSS measurements, benchmark algorithms for processing
 measurements into state estimates and visualization tools for measurements
 and state estimates.
 The modularity of `gnss_lib_py` is made possibly by the unifying
-`NavData` class, which contains methods to add, remove and modify
-numeric and string data consistently.
-We provide standard row names for `NavData` elements on the
+`NavData` class, with accompanying standard nomenclature, which can be
+found in the
 [reference page](https://gnss-lib-py.readthedocs.io/en/latest/reference/reference.html).
-These names ensure cross compatibility between different datasets and
-algorithms.
+The standard nomenclature ensures cross compatibility between different
+datasets and algorithms.
+
+`NavData` combines the readability of `pandas.DataFrame` with `numpy.ndarray`
+allowing for easy and fast access of numbers or strings.
+We also provide functionality to add, remove and modify numeric and
+string data consistently along with commonly needed supporting
+functionality.
 
 Documentation
 -------------
@@ -51,7 +57,7 @@ Code Organization
         ├── parsers/                  # Data parsers
         ├── utils/                    # GNSS and common utilities
         ├── visualizations/           # plotting functions
-        └── __init__.py
+        └── __init__.py               # Initialize gnss_lib_py
    ├── notebooks/                     # Interactive Jupyter notebooks
         ├── tutorials/                # Notebooks with tutorial code
    ├── results/                       # Location for result images/files
@@ -61,7 +67,7 @@ Code Organization
       ├── parsers/                    # Tests for files in parsers
       ├── utils/                      # Tests for files in utils
       ├── visualizations/             # Tests for files in visualizations
-      └── test_gnss_lib_py.py         # High level checks for repository
+      └── conftest.py                 # Common methods for tests
    ├── CONTRIBUTORS.md                # List of contributors
    ├── build_docs.sh                  # Bash script to build docs
    ├── poetry.lock                    # Poetry specific Lock file
@@ -70,14 +76,19 @@ Code Organization
 ```
 In the directory organization above:
 
-  * The `algorithms` directory contains localization algorithms that
+  * The `algorithms` directory contains algorithms that
     work by passing in a `NavData` class. Currently, the following
     algorithms are implemented in the `algorithms`:
 
       * Weighted Least Squares
       * Extended Kalman Filter
       * Calculating pseudorange residuals
       * Fault detection and exclusion
+
+  * The `navdata` directory defines the `NavData` class, its methods, and
+    functions that operate on `NavData` instances, like `sort`, `concat`,
+    and others.
+
   * The data parsers in the `parsers` directory allow for either loading
     GNSS data into `gnss_lib_py`'s unifying `NavData` class or parsing
     precise ephemerides data.
@@ -96,6 +107,10 @@ In the directory organization above:
     visualizations, calculating multi-GNSS satellite PVT information,
     satellite simulation, file operations, etc.
 
+  * The `visualizations` directory contains methods for plotting quantities
+    in `NavData`. It includes methods to plot metrics, positions on maps,
+    and skyplots of satellites visible from the receiver position.
+
 Installation
 ------------
 

docs/source/conf.py

@@ -37,7 +37,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'gnss_lib_py'
-copyright = '2022, Stanford NAV Lab'
+copyright = '2024, Stanford NAV Lab'
 author = 'Ashwin Kanhere, Derek Knowles'
 
 

docs/source/contributing/contributing.rst

@@ -16,12 +16,15 @@ In your issue, please include:
     * Your operating system name and version.
     * Any details about your local setup that might be helpful in
       troubleshooting.
-    * A minimal working example to reproduce the bug.
+    * A minimal working example (MWE) to reproduce the bug. An MWE
+      helps us reproduce the bug and troubleshoot the problem.
+      For more details on how to create an MWE, see
+      `this Stack Overflow guide <https://stackoverflow.com/help/minimal-reproducible-example>`.
 
 Feature requests and feedback
 -----------------------------
 
-The best way to   send feedback is to file an issue on
+The best way to any send feedback is to file an issue on
 `GitHub <https://github.com/Stanford-NavLab/gnss_lib_py/issues>`__.
 
 If you are proposing a feature:
@@ -31,8 +34,9 @@ If you are proposing a feature:
     * Keep the scope as narrow as possible, which will make it easier to
       implement.
     * This is a volunteer driven project and most contributions are a
-      result of other research projects. If you implement your requested
-      feature and submit a pull request, we will incorporate it.
+      result of other research projects. We welcome outside implementations
+      of additional features. If you implement your requested feature
+      and submit a pull request, we will incorporate it.
 
 Additional Contributing Pages
 -----------------------------

docs/source/contributing/development.rst

@@ -22,8 +22,12 @@ Standard GitHub Workflow
 
 2. If using poetry, follow the :ref:`developer install instructions<developer install>`
    to install pyenv, poetry, and the python dependencies. If using
-   :code:`pip` or :code:`conda` for package management instead, use
-   :code:`pip install -r requirements.txt` to install dependencies.
+   :code:`pip` or :code:`conda` for package management instead, install
+   dependencies using
+
+   .. code-block:: bash
+
+      pip install -r requirements.txt
 
 3. Create a local branch:
 
@@ -36,16 +40,21 @@ Standard GitHub Workflow
 
    If the feature branch includes new functionality, you must also:
 
-   * update the "Code Organization" section of the :code:`README.md`
-   * update the "Code Organization" section of
-     :code:`docs/source/index.rst` to match the :code:`README.md`
    * add a section in the appropriate tutorial notebook located in
      :code:`notebooks/tutorials/*`
    * if the feature is in a new file, import the file in the
      `module's import block <https://github.com/Stanford-NavLab/gnss_lib_py/blob/main/gnss_lib_py/__init__.py>`__.
 
+   If directory level changes were made, you must also:
+
+   * update the "Code Organization" section of the :code:`README.md`
+   * update the "Code Organization" section of
+     :code:`docs/source/index.rst` to match the :code:`README.md`
+
+
 5. Add tests for the newly added code and ensure the new code is covered.
-   See the :ref:`Testing<testing>` section for more details.
+   See the :ref:`Testing<testing>` and :ref:`Coverage<coverage>` pages
+   for more details.
 
 6. When you're done making changes run all the tests with:
 
@@ -93,9 +102,10 @@ Standard GitHub Workflow
     in the pull request, select the latest version release branch :code:`vX.Y.Z`
     (with the highest number of all such branches). *Do not target the*
     :code:`main` *branch in your pull request.* In the pull request,
-    add a code review request for a current maintainer of the repository.
-    The reviewers might add comments to ensure compliance with the rest
-    of the code.
+    add a code review request for a current maintainer of the repository
+    and provide a brief description of the implemented features.
+    The reviewers might add comments or suggest changes to ensure
+    compliance with the rest of the code.
 
 .. _navlab_dev:
 
@@ -119,14 +129,18 @@ NAVLab GitHub Workflow
 
    If the feature branch includes new functionality, you must also:
 
-   * update the "Code Organization" section of the :code:`README.md`
-   * update the "Code Organization" section of
-     :code:`docs/source/index.rst` to match the :code:`README.md`
    * add a section in the appropriate tutorial notebook located in
      :code:`notebooks/tutorials/*`
    * if the feature is in a new file, import the file in the
      `module's import block <https://github.com/Stanford-NavLab/gnss_lib_py/blob/main/gnss_lib_py/__init__.py>`__.
 
+   If directory level changes were made, you must also:
+
+   * update the "Code Organization" section of the :code:`README.md`
+   * update the "Code Organization" section of
+     :code:`docs/source/index.rst` to match the :code:`README.md`
+
+
 5. Add tests for the newly added code and ensure the new code is covered.
    See the :ref:`Testing<testing>` section for more details.
 
@@ -214,19 +228,22 @@ Pull Request Review Workflow
 3. Verify that documentation is complete and updated if necessary. See
    the :ref:`Documentation<documentation>` section for more details on
    what is expected.
-
    If the feature branch included new functionality, the following
    should have also been updated:
 
-   * the "Code Organization" section of the :code:`README.md`
-   * the "Code Organization" section of
-     :code:`docs/source/index.rst` to match the :code:`README.md`
    * the appropriate tutorial notebook located in
      :code:`notebooks/tutorials/*` with a simple example of the new
      functionality
    * if a new file was created, it should likely be imported in the
      `module's import block <https://github.com/Stanford-NavLab/gnss_lib_py/blob/main/gnss_lib_py/__init__.py>`__.
 
+   If the directory structure was modified, the following should also have
+   been updated:
+
+   * the "Code Organization" section of the :code:`README.md`
+   * the "Code Organization" section of
+     :code:`docs/source/index.rst` to match the :code:`README.md`
+
 4. Verify that all tests run on your system:
 
    .. code-block:: bash

docs/source/contributing/documentation.rst

@@ -16,9 +16,9 @@ We use `numpy docstrings
 <https://numpydoc.readthedocs.io/en/latest/format.html>`__
 for all documentation within this package. You can see some example
 numpy docstrings `here <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html#example-numpy>`__.
-In addition to class and function docstrings, any code
-whose behaviour or purpose is not obvious, should be independently
-commented.
+In addition to class and function docstrings, any line of code
+whose behaviour or purpose is not obvious, should be have a brief explanation
+near the code using comments.
 
 Additional documentation guidelines
 -----------------------------------
@@ -31,6 +31,11 @@ titled References and include the reference as shown below in the
 docstring. (Remove the block comment flag when inserting in already
 written docstrings)
 
+The same reference number cannot be used across multiple methods or classes
+in the same file. If you want to use the same reference in multiple methods,
+you will have to update the reference number each time that the reference
+is added.
+
 .. code-block:: python
 
     """
@@ -53,14 +58,22 @@ following:
     * :code:`bool`
     * :code:`int`
     * :code:`float`
-    * :code:`list` (include shape in the description)
+    * :code:`list` (include type of each list element in the description)
     * :code:`dict` (include key type and value type in description)
     * :code:`np.ndarray` (include shape in the description). Where possible,
-      single axis arrays should be rows and time should be across
-      the columns
+      single axis arrays should be rows and time/different measurements
+      should be across the columns
     * :code:`pd.DataFrame`
     * :code:`gnss_lib_py.navdata.navdata.NavData`
 
+If methods can accept/return multiple types of values, combine them in the
+parameter/return type :code:`parameter_name : list/np.ndarray` and provide
+additional details in the description.
+
+Similarly, if a method accepts/returns a particular combination of types,
+mention them in the type like :code:`parameter_name : tuple of np.ndarray`
+and provide details in the description.
+
 PEP 8 Style Guide
 -----------------
 We also follow the `PEP 8 Python Style Guide
@@ -120,22 +133,33 @@ Citations should be added on a function by function basis.
 If a function is built on the implementation from another repository,
 include the license and attribution as required by the original author.
 
+Use the :code:`Notes` and :code:`References` sections in the docstring
+to ensure proper citations, links, and explanations are provided.
+
 Miscellaneous Style Notes
 -------------------------
-    * Vectors (lists, np.ndarrays, etc.) for a single time instance
+    * Vectors (lists, np.ndarrays, etc.) for a single time/measurement instance
       should be column vectors.
     * Collections of vectors should be 2D structures with each column
       representing the value of the vector for a particular time. In
       this convention, time varies across columns while physical
       quantities vary across rows.
+    * When there are multiple measurements per time instance, there should
+      be a row specifying the time of each measurement. Each measurement
+      instance should be a column vector. Different types of information
+      should be rows. Eg., for 10 measurements across 4 time instances,
+      containing 6 types of information, the shape of the data should be
+      :code:`(6, 40)`. Ideally, the first 10 columns should correspond to
+      the same time instance, the next 10 for the next time instance, and
+      so on.
     * Assert errors and tell the user what caused that particular error.
       For example, if a column vector is passed instead of a row vector,
       the assertion error message should say that a row vector was
       expected. We maintain functions in :code:`utils/*` that might be
       useful for performing such checks. Please check if an existing
       function performs the desired task before adding new functions.
     * Write units in brackets in comments and docstrings. For example,
-      [m].
+      [m] for values of distance/position and [m/s] for velocities.
 
 
 Adding to Documentation Pages
@@ -151,6 +175,9 @@ documentation for any syntax queries.
 Building Documentation
 ----------------------
 
+Updating Documentation Configuration
+++++++++++++++++++++++++++++++++++++
+
 If you changed any directory names in the repository:
 
     * update :code:`docs/conf.py` to reflect correct directory names
@@ -166,6 +193,9 @@ If you wish to add python dependencies:
 
 If you wish to remove python dependencies, use :code:`poetry remove package`.
 
+Building Documentation Locally
+++++++++++++++++++++++++++++++
+
 If you're using :code:`poetry`, after the above, you can run the helper
 tool from the main directory that will automatically rebuild references
 and build a local HTML copy of the documentation:
@@ -180,3 +210,11 @@ a browser to view your local copy.
 If you encounter errors while using the :code:`build_docs.sh` tool, refer
 to previously documented solutions in the
 :ref:`troubleshooting page <build_errors>`.
+
+Building Documentation on ReadTheDocs
++++++++++++++++++++++++++++++++++++++
+
+Documentation on readthedocs.com is automatically built when a new pull
+request is submitted through our GitHub Actions. Check the corresponding
+branch of the documentation after you have submitted a pull request
+`here <https://readthedocs.org/projects/gnss-lib-py/versions/>`.