Merge pull request #1 from ssolson/automate_docs

Automate docs

.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: Build and Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches: [main]
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          submodules: recursive
+          fetch-depth: 0
+
+      - name: Setup Conda Environment
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+          activate-environment: mhkit-docs
+          environment-file: environment.yml
+          auto-activate-base: false
+
+      - name: Build Documentation
+        shell: bash -l {0}
+        run: |
+          cd docs
+          rm -rf _build/*
+          sphinx-build -b html source _build/html
+          # Create .nojekyll file to prevent GitHub Pages from ignoring files that begin with an underscore
+          touch _build/html/.nojekyll
+
+      - name: Deploy to GitHub Pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/_build/html
+          force_orphan: true
+          enable_jekyll: false
+          full_commit_message: ${{ github.event.head_commit.message }}

.gitignore

@@ -1,19 +1,16 @@
-# File Types
-.buildinfo
-.buildinfo.bak
-*.tws
+# Documentation builds
+docs/_build/
+docs/doctrees/
+
+# Backup files
 *~
 *.swp
+*.tws
+.buildinfo
+.buildinfo.bak
 
-
-# Directories
-*/latex/*
+# IDE settings
 */.vscode/*
 
 # Other
 issues.md
-
-docs/doctrees
-docs/.doctrees
-docs/**/doctrees
-docs/**/.doctrees

README.md

@@ -1,142 +1,160 @@
-
 # How to Update the [MHKiT Documentation Website](https://MHKiT-Software.github.io/MHKiT/)
-The MHKiT documentation is developed as restructured text files that are compiled by [Sphinx](http://www.sphinx-doc.org/en/master/) into html files and then uploaded to the [MHKiT Documentation Repository](https://github.com/MHKiT-Software/MHKiT). Using Sphinx, GitHub renders the documentation on the [MHKiT Documentation Repository](https://github.com/MHKiT-Software/MHKiT/) as the [MHKiT Documentation Website](https://MHKiT-Software.github.io/MHKiT/). This guide will help the user to download the documentation, modify the documentation, build the documentation locally, and push changes back up to the repository.
 
+The MHKiT documentation is developed as restructured text files that are compiled by [Sphinx](http://www.sphinx-doc.org/en/master/) into html files and then uploaded to the [MHKiT Documentation Repository](https://github.com/MHKiT-Software/MHKiT). Using Sphinx, GitHub renders the documentation on the [MHKiT Documentation Repository](https://github.com/MHKiT-Software/MHKiT/) as the [MHKiT Documentation Website](https://MHKiT-Software.github.io/MHKiT/). This guide will help the user to download the documentation, modify the documentation, build the documentation locally, and push changes back up to the repository.
 
 ## Requirements
 
 To update the MHKiT documentation you will need Python 3.6+, Git, Sphinx, and a GitHub account. This documentation assumes the user has a working version of Python installed (We recommend Anaconda Python, during installation check the add Python to Path) and a GitHub account but will cover the needed Python Sphinx package installation.
 
 ### Step 1. Fork the Repository & Clone to local machine
-  - To update the documentation a user will need to "fork" this repository. This simply means that you are creating your own copy of this repository that you can edit.
-  - Once forked you can "clone" (this will download your fork to your machine) the repository to your local machine using the command line.
-  - Using the command line navigate to the file system location you would like to keep the documentation repository clone the documentation. Replacing the username and repository name to the correct values for you. This link can be automatically generated on your fork by copying the link visible after clicking clone on your repository page. The repository name will be assumed to be MHKiT in the remaining commands.
-  ```bash
-    git clone https://github.com/USERNAME/REPOSITORYNAME.git
-  ```
-  - Once cloned use the command line to change directories into the folder created by the clone to update the  MHKiT-Python and MHKiT-MATLAB [submodules].
-
-  ```bash
-     cd MHKiT
-     git submodule init
-     git submodule update --remote
-  ```
-  The ``MHKiT-Python`` and ``MHKiT-MATLAB`` folders should now contain source code.
-
-  To build the Python API documentation for submitting a pull request you will want to use the submodule MHKiT-Python included here. To do so first uninstall any MHKiT you may have and then use the python package manager to install this MHKiT submodule.
-
-  ```bash
-  pip uninstall mhkit
-  cd MHKiT-Python
-  pip install -e .
-  ```
-   **NOTE:** After building the documentation (see below) be sure to reinstall your MHKiT-Python distribution from pypi (e.g. `pip install mhkit`) or from your fork of the repository as an editable package (e.g. `pip install -e /path/to/my/fork/of/MHKiT-Python`)
 
-### Step 2. Download/Install [Sphinx](http://www.sphinx-doc.org/en/stable/index.html) package and extensions
-  - [Sphinx]((http://www.sphinx-doc.org/en/master/usage/installation.html)) is a python package used to create the MHKiT documentation.
+- To update the documentation a user will need to "fork" this repository. This simply means that you are creating your own copy of this repository that you can edit.
+- Once forked you can "clone" (this will download your fork to your machine) the repository to your local machine using the command line.
+- Using the command line navigate to the file system location you would like to keep the documentation repository clone the documentation. Replacing the username and repository name to the correct values for you. This link can be automatically generated on your fork by copying the link visible after clicking clone on your repository page. The repository name will be assumed to be MHKiT in the remaining commands.
+
+```bash
+  git clone https://github.com/USERNAME/REPOSITORYNAME.git
+```
+
+- Once cloned use the command line to change directories into the folder created by the clone to update the MHKiT-Python and MHKiT-MATLAB [submodules].
+
+```bash
+   cd MHKiT
+   git submodule init
+   git submodule update --remote
+```
 
-  - Install Sphinx from the command line
-   **NOTE:** You may need to add PROXY settings ([see info here](https://cinhtau.net/2018/04/16/python-proxy-windows/))
-
-    ```pip install -U Sphinx```
-
-    - Sphinx --> Version: 8.1.3
+The `MHKiT-Python` and `MHKiT-MATLAB` folders should now contain source code.
 
-  - Use the command line to install the needed Sphinx submodules (BibTex, MATLAB theme, rtd theme, NB Sphinx, and google analytics) and additional dependencies
+### Step 2. Download/Install Sphinx and Dependencies
 
-     ```pip install -U sphinxcontrib-bibtex sphinxcontrib-matlabdomain sphinx_rtd_theme nbsphinx sphinxcontrib-googleanalytics ipython```
+#### Option 1: Using conda (recommended)
 
-      - nbsphinx  --> Version: 0.9.5
+1. Create and activate the conda environment:
 
-      - sphinxcontrib-matlabdomain  --> Version: 0.22.1
+```bash
+conda env create -f environment.yml
+conda activate mhkit-docs
+```
 
-      - sphinxcontrib-bibtex --> Version: 2.6.3
+#### Option 2: Manual Installation
 
-      - sphinx-rtd-theme --> Version: 3.0.2
+If you prefer to install packages manually:
 
-      - sphinxcontrib-googleanalytics  --> Version: 0.4
-
-    ```conda install pandoc```
+1. Install the local MHKiT-Python submodule:
+
+```bash
+pip uninstall mhkit  # Remove any existing MHKiT installation
+cd MHKiT-Python
+pip install -e .     # Install the submodule in editable mode
+```
+
+**NOTE:** After building the documentation, remember to reinstall your preferred MHKiT-Python distribution:
+
+- From PyPI: `pip install mhkit`
+- From your fork: `pip install -e /path/to/your/fork/of/MHKiT-Python`
+
+2. Install Sphinx and dependencies:
+
+```bash
+pip install -U Sphinx==8.1.3
+pip install -U sphinxcontrib-bibtex==2.6.3 sphinxcontrib-matlabdomain==0.22.1 sphinx-rtd-theme==3.0.2 nbsphinx==0.9.5 sphinxcontrib-googleanalytics==0.4 ipython
+conda install pandoc
+```
 
 You are now ready to begin modifying and building the MHKiT documentation.
 
 ## Step 3. Modify the Documentation
 
-- The restructured text files used to build the documentation are located in the ``/MHKiT/docs/source`` directory (Check the [Sphinx Website](http://www.sphinx-doc.org/en/master/) for information about the folder structure).
+- The restructured text files used to build the documentation are located in the `/MHKiT/docs/source` directory (Check the [Sphinx Website](http://www.sphinx-doc.org/en/master/) for information about the folder structure).
 - Before modifying the documentation we recommend creating a feature branch and not modifying your fork's main branch. A feature branch can be created using the commands
+
 ```bash
 git branch featureBranchName
 git checkout featureBranchName
 ```
+
 - Now you can use a text editor to modify any restructured text file (files with `.rst` extension, e.g. `index.rst`).
 - Once you are done editing, move to Step 4
 
 ## Step 4. Build the [MHKiT Documentation](https://MHKiT-Software.github.io/MHKiT/)
-- To locally build the documentation use the command line to move into the ``/MHKiT/docs`` folder then `make html`
+
+- To locally build the documentation use the command line to move into the `/MHKiT/docs` folder then `make html`
+
 ```bash
     cd docs
     make clean
     make html
 ```
-Using your machine's file explorer navigate to MHKiT/docs and use an Internet browser (i.e. Chrome, Safari, Edge, etc. ) to open `index.html` to view modifications to the documentation source made above.
 
+Using your machine's file explorer navigate to MHKiT/docs and use an Internet browser (i.e. Chrome, Safari, Edge, etc. ) to open `index.html` to view modifications to the documentation source made above.
 
 ## Step 5. Update to the [MHKiT Documentation](https://MHKiT-Software.github.io/MHKiT/)
-- Once changes have been made the user can push the changes back up to their fork
 
+- Once changes have been made the user can push the changes back up to their fork
 
   ```Shell
   git status
   ```
+
   - The status will return a list of files that have been modified. If you want to commit all of the changed files you can use `git add --all` otherwise use `git add fileName` where `fileName` is either the file or a list of space-separated files the user wishes to add.
   - Commit the changes with a message documenting what has been changed
+
   ```
   git commit -m 'A descriptive message here describing why or what was changed in the documentation'
   ```
-  - Finally, push the changes to your fork's (``yourFork``) feature branch (``featureBranchName``).
+
+  - Finally, push the changes to your fork's (`yourFork`) feature branch (`featureBranchName`).
+
   ```
   git push -u yourFork featureBranchName
   ```
-  - If you did not create a feature branch simply type `git push` 
+
+  - If you did not create a feature branch simply type `git push`
 
 ## Step 6. Submit a Pull Request
+
 - Submit a pull request to merge the revisions on your fork with main, https://github.com/MHKiT-Software/MHKiT/pulls
 
 # Best Practices
-  - Run spell check (not built into most text editors)
-  - Update the MHKiT-Python and MHKiT-MATLAB submodules ``git submodule init`` ``git submodule update --remote``, refer to https://git-scm.com/book/en/v2/Git-Tools-Submodules for more information
-  - When compiling the website, ``make clean`` and then ``make html``
+
+- Run spell check (not built into most text editors)
+- Update the MHKiT-Python and MHKiT-MATLAB submodules `git submodule init` `git submodule update --remote`, refer to https://git-scm.com/book/en/v2/Git-Tools-Submodules for more information
+- When compiling the website, `make clean` and then `make html`
 
 ## Formatting Guidelines
-  - `*.m` or `*.py` syntax to refer to file extension
-  - use ``insert code`` to reference code
-  - use API documentation from source code
-  - Title `####` with overline
-  - Heading 1 `======`
-  - Heading 2 `------`
-  - Heading 3 `^^^^^^`
-  - Heading 4 `""""""`
-  - Heading 5 `++++++`
-  - Made sure header underline is for full length of header text
-  - Use this style guide: https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html
+
+- `*.m` or `*.py` syntax to refer to file extension
+- use `insert code` to reference code
+- use API documentation from source code
+- Title `####` with overline
+- Heading 1 `======`
+- Heading 2 `------`
+- Heading 3 `^^^^^^`
+- Heading 4 `""""""`
+- Heading 5 `++++++`
+- Made sure header underline is for full length of header text
+- Use this style guide: https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html
 
 ## Terminology Guidelines
-  - DataFrame (not dataframe)
-  - MATLAB (not Matlab)
-  - Python (not python)
-  - pandas (not Pandas)
-  - MHKiT (not mhkit)
-  - open-source (not open source)
-  - time-series (not timeseries or time series)
-  - time-domain (not time domain)
-  - frequency-domain (not frequency domain)
-  - MHKiT-Python (or link to MHKiT-Python when referring to the repo)
-  - MHKiT-MATLAB (MHKiT-MATLAB when referring to the repo)
-  - MHKiT (Marine and Hydrokinetic Toolkit)
+
+- DataFrame (not dataframe)
+- MATLAB (not Matlab)
+- Python (not python)
+- pandas (not Pandas)
+- MHKiT (not mhkit)
+- open-source (not open source)
+- time-series (not timeseries or time series)
+- time-domain (not time domain)
+- frequency-domain (not frequency domain)
+- MHKiT-Python (or link to MHKiT-Python when referring to the repo)
+- MHKiT-MATLAB (MHKiT-MATLAB when referring to the repo)
+- MHKiT (Marine and Hydrokinetic Toolkit)
 
 ## Modules Template
+
 All modules in MHKiT should be briefly described in the "Module Overview" Section.
-Below is a template that can be used for a new MHKiT module (fix title 
+Below is a template that can be used for a new MHKiT module (fix title
 characters when adding a section):
 
 NAME Module
@@ -147,8 +165,8 @@ Brief description of what the module dose.
 API Documentation
 <br />--------------------
 
-- `Python NAME API Documentation <mhkit-python/api.NAME.html>`_
-- `MATLAB NAME API Documentation <mhkit-matlab/api.NAME.html>`_
+- `Python NAME API Documentation <mhkit-python/api.NAME.html>`\_
+- `MATLAB NAME API Documentation <mhkit-matlab/api.NAME.html>`\_
 
 Examples
 <br />--------------
@@ -162,11 +180,14 @@ Submodules
 
 The NAME module contains the following submodules:
 
-* ``SUBMODULE_NAME``: one sentence description of the submodule. Calculations are based on `IEC TS XXXXX-XXX:20XX EDX <LINK>`
-* ``SUBMODULE_NAME``: etc...
+- `SUBMODULE_NAME`: one sentence description of the submodule. Calculations are based on `IEC TS XXXXX-XXX:20XX EDX <LINK>`
+- `SUBMODULE_NAME`: etc...
 
 IEC/TS XXXXX-XXX
 <br />---------------------------
 
 Recommends proper use of the module per relevant IEC standards.
 
+## Documentation Builds
+
+The documentation is automatically built and deployed using GitHub Actions when changes are pushed to the main branch. You can view the latest documentation at https://MHKiT-Software.github.io/MHKiT/.