Merge pull request #68 from Stanford-NavLab/derek/naming-conventions

derek/naming-conventions

Author: kanhereashwin

.github/workflows/python-app.yml

@@ -66,3 +66,28 @@ jobs:
     - name: Test if docs are building
       run: |
         ./build_docs.sh
+  readme:
+    runs-on: ubuntu-latest
+    name: Check if index.rst and README.md weren't changed together
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Get changed files since last remote commit
+        id: changed-files
+        uses: tj-actions/changed-files@v27
+        with:
+          since_last_remote_commit: "true"
+
+      - 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')
+        run: |
+          echo "README.md has changed but index.rst has not!"
+          exit 1
+
+      - name: Check if README.md changed when index.rst file changes
+        if: contains(steps.changed-files.outputs.modified_files, 'docs/source/index.rst') && !contains(steps.changed-files.outputs.modified_files, 'README.md')
+        run: |
+          echo "index.rst has changed but README.md has not!"
+          exit 1

.gitignore

@@ -12,8 +12,9 @@ results/*
 !results/.gitkeep
 
 # ignore downloaded csv files in notebook tutorials
-notebooks/tutorials/Pixel4XL_derived.csv
-docs/source/tutorials/*.csv
+*.csv
+!data/unit_test/*/*.csv
+!notebooks/tutorials/myreceiver.csv
 
 #Excluding VS Code files
 .vscode/*

README.md

@@ -61,8 +61,7 @@ Code Organization
    ├── build_docs.sh                  # Bash script to build docs
    ├── poetry.lock                    # Poetry specific Lock file
    ├── pyproject.toml                 # List of package dependencies
-   ├── requirements.txt               # List of packages for pip install
-   └── setup.py                       # Setup file
+   └── requirements.txt               # List of packages for pip install
 ```
 In the directory organization above:
 

build_docs.sh

@@ -1,22 +1,31 @@
 #!/bin/bash
+# export requirements.txt for buildings docs
 poetry export -f requirements.txt --output ./docs/source/requirements.txt --dev --without-hashes
 cd docs
+
 echo "Rebuilding References"
-rm -rv ./source/reference/algorithms/*
-poetry run sphinx-apidoc -f -M -o ./source/reference/algorithms/ ./../gnss_lib_py/algorithms/
-rm -rv ./source/reference/parsers/*
-poetry run sphinx-apidoc -f -M -o ./source/reference/parsers/ ./../gnss_lib_py/parsers/
-rm -rv ./source/reference/utils/*
-poetry run sphinx-apidoc -f -M -o ./source/reference/utils/ ./../gnss_lib_py/utils/
-rm -rv ./source/reference/test_algorithms/*
-poetry run sphinx-apidoc -f -M -o ./source/reference/test_algorithms/ ./../tests/algorithms/
-rm -rv ./source/reference/test_parsers/*
-poetry run sphinx-apidoc -f -M -o ./source/reference/test_parsers/ ./../tests/parsers/
-rm -rv ./source/reference/test_utils/*
-poetry run sphinx-apidoc -f -M -o ./source/reference/test_utils/ ./../tests/utils/
-echo "Cleaning up existing make"
+rm -r ./source/reference/algorithms/*
+poetry run sphinx-apidoc -f -M -q -o ./source/reference/algorithms/ ./../gnss_lib_py/algorithms/
+rm -r ./source/reference/parsers/*
+poetry run sphinx-apidoc -f -M -q -o ./source/reference/parsers/ ./../gnss_lib_py/parsers/
+rm -r ./source/reference/utils/*
+poetry run sphinx-apidoc -f -M -q -o ./source/reference/utils/ ./../gnss_lib_py/utils/
+rm -r ./source/reference/test_algorithms/*
+poetry run sphinx-apidoc -f -M -q -o ./source/reference/test_algorithms/ ./../tests/algorithms/
+rm -r ./source/reference/test_parsers/*
+poetry run sphinx-apidoc -f -M -q -o ./source/reference/test_parsers/ ./../tests/parsers/
+rm -r ./source/reference/test_utils/*
+poetry run sphinx-apidoc -f -M -q -o ./source/reference/test_utils/ ./../tests/utils/
+
+# remove previously downloaded .csv files if they exist
+rm ./source/*/*.csv
+
+echo "Cleaning existing make"
 poetry run make clean
+
 echo "Building docs in html"
 poetry run make html
+
+# export requirements.txt for setup.py
 cd ..
 poetry export -f requirements.txt --output ./requirements.txt --without-hashes

docs/source/contributing/development.rst

@@ -33,6 +33,14 @@ Standard GitHub Workflow
 5. Make changes locally and document them appropriately. See the
    :ref:`Documentation<documentation>` section for more details.
 
+   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/*`
+
 6. Add tests for the newly added code and ensure the new code is covered.
    See the :ref:`Testing<testing>` section for more details.
 
@@ -87,6 +95,14 @@ NAVLab GitHub Workflow
 4. Make changes locally and document them appropriately. See the
    :ref:`Documentation<documentation>` section for more details.
 
+   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/*`
+
 5. Add your name to the `contributors list <https://github.com/Stanford-NavLab/gnss_lib_py/blob/main/CONTRIBUTORS.sh>`__.
 
 6. When you're done making changes run all the tests with:
@@ -156,6 +172,16 @@ Pull Request Review Workflow
    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
+
 4. Verify that all tests run on your system:
 
    .. code-block:: bash

docs/source/index.rst

@@ -64,8 +64,7 @@ Code Organization
    ├── build_docs.sh                  # Bash script to build docs
    ├── poetry.lock                    # Poetry specific Lock file
    ├── pyproject.toml                 # List of package dependencies
-   ├── requirements.txt               # List of packages for pip install
-   └── setup.py                       # Setup file
+   └── requirements.txt               # List of packages for pip install
 
 In the directory organization above:
 

docs/source/install.rst

@@ -6,17 +6,27 @@ Install
 Prerequisites
 -------------
 
-:code:`gnss_lib_py` is written in Python and requires basic familiarity
-with Python classes, functions and associated syntax.
+| **Python:** >=3.8, <3.11
+| **Operating System:** Linux, Windows, MacOS
 
-:code:`gnss_lib_py` is developed in Python 3.8.9 in Ubuntu 20 and
-Ubuntu 20 for WSL2.
 All :code:`gnss_lib_py` classes and methods are tested in Python 3.8
 and 3.10 in the latest Ubuntu, MacOS and Windows versions.
+:code:`gnss_lib_py` is developed in Python 3.8.9 in Ubuntu 20/22 and
+Ubuntu 20 for WSL2.
 
 Standard Installation
 ---------------------
 
+1. :code:`gnss_lib_py` is available through :code:`pip` installation
+   with:
+
+   .. code-block:: bash
+
+      pip install gnss-lib-py
+
+Editable Installation
+---------------------
+
 1. Clone the GitHub repository:
 
    .. code-block:: bash
@@ -31,7 +41,7 @@ Standard Installation
 
 3. Update pip version.
 
-   a. For Linux:
+   a. For Linux and MacOS:
 
       .. code-block:: bash
 
@@ -64,8 +74,8 @@ Developer Installation
 This project is being developed using :code:`pyenv` and :code:`poetry`
 for python version and environment control respectively.
 
-Ubuntu/WSL2
-+++++++++++
+Linux/WSL2 and MacOS
+++++++++++++++++++++
 
 1. Install :code:`pyenv` using the installation instructions
    `here <https://github.com/pyenv/pyenv#installation>`__. The steps are