{"id":21580918,"url":"https://github.com/mhkit-software/mhkit","last_synced_at":"2025-07-02T20:08:14.297Z","repository":{"id":41994199,"uuid":"229150357","full_name":"MHKiT-Software/MHKiT","owner":"MHKiT-Software","description":"MHKiT Documentation","archived":false,"fork":false,"pushed_at":"2025-02-05T16:57:53.000Z","size":278204,"stargazers_count":4,"open_issues_count":5,"forks_count":14,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-18T08:13:20.361Z","etag":null,"topics":["marine-renewable-energy","mhk","mhkit","mhkit-documentation","mhkit-matlab","mhkit-python"],"latest_commit_sha":null,"homepage":"https://MHKiT-Software.github.io/MHKiT/","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MHKiT-Software.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-12-19T22:43:57.000Z","updated_at":"2025-02-05T16:54:43.000Z","dependencies_parsed_at":"2022-08-12T01:41:09.369Z","dependency_job_id":"a44483bf-617c-4a9a-b11b-a209a5047c7f","html_url":"https://github.com/MHKiT-Software/MHKiT","commit_stats":{"total_commits":183,"total_committers":14,"mean_commits":"13.071428571428571","dds":0.5792349726775956,"last_synced_commit":"beaa580adee6389d93181ae4cd9886b7b5df429e"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MHKiT-Software/MHKiT","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MHKiT-Software%2FMHKiT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MHKiT-Software%2FMHKiT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MHKiT-Software%2FMHKiT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MHKiT-Software%2FMHKiT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MHKiT-Software","download_url":"https://codeload.github.com/MHKiT-Software/MHKiT/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MHKiT-Software%2FMHKiT/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263208050,"owners_count":23430676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["marine-renewable-energy","mhk","mhkit","mhkit-documentation","mhkit-matlab","mhkit-python"],"created_at":"2024-11-24T14:10:17.393Z","updated_at":"2025-07-02T20:08:14.259Z","avatar_url":"https://github.com/MHKiT-Software.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# How to Update the [MHKiT Documentation Website](https://MHKiT-Software.github.io/MHKiT/)\n\nThe 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.\n\n## Requirements\n\nTo 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.\n\n### Step 1. Fork the Repository \u0026 Clone to local machine\n\n- 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.\n- Once forked you can \"clone\" (this will download your fork to your machine) the repository to your local machine using the command line.\n- 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.\n\n```bash\n  git clone https://github.com/USERNAME/REPOSITORYNAME.git\n```\n\n- 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].\n\n```bash\n   cd MHKiT\n   git submodule init\n   git submodule update --remote\n```\n\nThe `MHKiT-Python` and `MHKiT-MATLAB` folders should now contain source code.\n\n### Step 2. Download/Install Sphinx and Dependencies\n\n#### Option 1: Using conda (recommended)\n\n1. Create and activate the conda environment:\n\n```bash\nconda env create -f environment.yml\nconda activate mhkit-docs\n```\n\n#### Option 2: Manual Installation\n\nIf you prefer to install packages manually:\n\n1. Install the local MHKiT-Python submodule:\n\n```bash\npip uninstall mhkit  # Remove any existing MHKiT installation\ncd MHKiT-Python\npip install -e .     # Install the submodule in editable mode\n```\n\n**NOTE:** After building the documentation, remember to reinstall your preferred MHKiT-Python distribution:\n\n- From PyPI: `pip install mhkit`\n- From your fork: `pip install -e /path/to/your/fork/of/MHKiT-Python`\n\n2. Install Sphinx and dependencies:\n\n```bash\npip install -U Sphinx==8.1.3\npip 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\nconda install pandoc\n```\n\nYou are now ready to begin modifying and building the MHKiT documentation.\n\n## Step 3. Modify the Documentation\n\n- 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).\n- 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\n\n```bash\ngit branch featureBranchName\ngit checkout featureBranchName\n```\n\n- Now you can use a text editor to modify any restructured text file (files with `.rst` extension, e.g. `index.rst`).\n- Once you are done editing, move to Step 4\n\n## Step 4. Build the [MHKiT Documentation](https://MHKiT-Software.github.io/MHKiT/)\n\n- To locally build the documentation use the command line to move into the `/MHKiT/docs` folder then `make html`\n\n```bash\n    cd docs\n    make clean\n    make html\n```\n\nUsing 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.\n\n## Step 5. Update to the [MHKiT Documentation](https://MHKiT-Software.github.io/MHKiT/)\n\n- Once changes have been made the user can push the changes back up to their fork\n\n  ```Shell\n  git status\n  ```\n\n  - 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.\n  - Commit the changes with a message documenting what has been changed\n\n  ```\n  git commit -m 'A descriptive message here describing why or what was changed in the documentation'\n  ```\n\n  - Finally, push the changes to your fork's (`yourFork`) feature branch (`featureBranchName`).\n\n  ```\n  git push -u yourFork featureBranchName\n  ```\n\n  - If you did not create a feature branch simply type `git push`\n\n## Step 6. Submit a Pull Request\n\n- Submit a pull request to merge the revisions on your fork with main, https://github.com/MHKiT-Software/MHKiT/pulls\n\n# Best Practices\n\n- Run spell check (not built into most text editors)\n- 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\n- When compiling the website, `make clean` and then `make html`\n\n## Formatting Guidelines\n\n- `*.m` or `*.py` syntax to refer to file extension\n- use `insert code` to reference code\n- use API documentation from source code\n- Title `####` with overline\n- Heading 1 `======`\n- Heading 2 `------`\n- Heading 3 `^^^^^^`\n- Heading 4 `\"\"\"\"\"\"`\n- Heading 5 `++++++`\n- Made sure header underline is for full length of header text\n- Use this style guide: https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html\n\n## Terminology Guidelines\n\n- DataFrame (not dataframe)\n- MATLAB (not Matlab)\n- Python (not python)\n- pandas (not Pandas)\n- MHKiT (not mhkit)\n- open-source (not open source)\n- time-series (not timeseries or time series)\n- time-domain (not time domain)\n- frequency-domain (not frequency domain)\n- MHKiT-Python (or link to MHKiT-Python when referring to the repo)\n- MHKiT-MATLAB (MHKiT-MATLAB when referring to the repo)\n- MHKiT (Marine and Hydrokinetic Toolkit)\n\n## Modules Template\n\nAll modules in MHKiT should be briefly described in the \"Module Overview\" Section.\nBelow is a template that can be used for a new MHKiT module (fix title\ncharacters when adding a section):\n\nNAME Module\n\u003cbr /\u003e====================\n\nBrief description of what the module dose.\n\nAPI Documentation\n\u003cbr /\u003e--------------------\n\n- `Python NAME API Documentation \u003cmhkit-python/api.NAME.html\u003e`\\_\n- `MATLAB NAME API Documentation \u003cmhkit-matlab/api.NAME.html\u003e`\\_\n\nExamples\n\u003cbr /\u003e--------------\n\n- Bulleted list of linked examples\n- pertaining to this module.\n- Tag modules in docs/source/examples.rst as appropriate.\n\nSubmodules\n\u003cbr /\u003e--------------\n\nThe NAME module contains the following submodules:\n\n- `SUBMODULE_NAME`: one sentence description of the submodule. Calculations are based on `IEC TS XXXXX-XXX:20XX EDX \u003cLINK\u003e`\n- `SUBMODULE_NAME`: etc...\n\nIEC/TS XXXXX-XXX\n\u003cbr /\u003e---------------------------\n\nRecommends proper use of the module per relevant IEC standards.\n\n## Documentation Builds\n\nThe 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/.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmhkit-software%2Fmhkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmhkit-software%2Fmhkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmhkit-software%2Fmhkit/lists"}