From af8fc7c650750c92b8029896163154ee6e4289f4 Mon Sep 17 00:00:00 2001 From: PhazonicRidley Date: Wed, 17 Jan 2024 13:13:46 -0800 Subject: [PATCH] :lipstick: Clean up a few typos and updated the README --- .gitignore | 192 ++++++++++++++++++++++++++++- README.md | 46 +++++-- sphinx/_templates/guide_links.html | 3 +- sphinx/index.rst | 5 +- 4 files changed, 226 insertions(+), 20 deletions(-) diff --git a/.gitignore b/.gitignore index f4771ad1c..59568f433 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,6 @@ # File created using '.gitignore Generator' for Visual Studio Code: https://bit.ly/vscode-gig -# Created by https://www.toptal.com/developers/gitignore/api/linux,macos,windows -# Edit at https://www.toptal.com/developers/gitignore?templates=linux,macos,windows +# Created by https://www.toptal.com/developers/gitignore/api/windows,macos,linux,python,venv +# Edit at https://www.toptal.com/developers/gitignore?templates=windows,macos,linux,python,venv ### Linux ### *~ @@ -50,6 +50,190 @@ Temporary Items # iCloud generated files *.icloud +### Python ### +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# poetry +# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control +#poetry.lock + +# pdm +# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. +#pdm.lock +# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it +# in version control. +# https://pdm.fming.dev/#use-with-ide +.pdm.toml + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# PyCharm +# JetBrains specific template is maintained in a separate JetBrains.gitignore that can +# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore +# and can be added to the global gitignore or merged into this file. For a more nuclear +# option (not recommended) you can uncomment the following to ignore the entire idea folder. +#.idea/ + +### Python Patch ### +# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration +poetry.toml + +# ruff +.ruff_cache/ + +# LSP config files +pyrightconfig.json + +### venv ### +# Virtualenv +# http://iamzed.com/2009/05/07/a-primer-on-virtualenv/ +[Bb]in +[Ii]nclude +[Ll]ib +[Ll]ib64 +[Ll]ocal +[Ss]cripts +pyvenv.cfg +pip-selfcheck.json + ### Windows ### # Windows thumbnail cache files Thumbs.db @@ -76,7 +260,7 @@ $RECYCLE.BIN/ # Windows shortcuts *.lnk -# End of https://www.toptal.com/developers/gitignore/api/linux,macos,windows +# End of https://www.toptal.com/developers/gitignore/api/windows,macos,linux,python,venv # Custom rules (everything added below won't be overriden by 'Generate .gitignore File' if you use 'Update' option) @@ -86,4 +270,4 @@ sphinx/output/ .vscode/ mkdocs/api -library_merger_devel.sh \ No newline at end of file +library_merger_devel.sh diff --git a/README.md b/README.md index 16158d366..d80c11d92 100644 --- a/README.md +++ b/README.md @@ -4,28 +4,52 @@ Organization wide repo for docs, assets, and tools any other static information. ## Updating the docs -libhal uses [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) to -generate our documentation. +libhal uses [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) for our static documentation and [sphinx](https://www.sphinx-doc.org/en/master/) for our API documentation -If you'd like to contribute to the libhal website and documentation you can do -so by first installing `mkdocs-material`. +If you'd like to contribute to the libhal website and documentation you can do so by quickly setting up the enviornement by running the following commands. Please note that the build script is designed for a bash environment and is intended to be used on unix-based operating systems. The documentation is fully compatible with Windows, however you will need to write your own `.bat` install script or run the commands individually (as well as switch from bash's commands to powershell or command prompt's variants of them). + +Please first install python 3.10 or later. Then run the following to install the required packages for running the documentation. ```bash -pip install mkdocs-material +pip install -r requirements.txt ``` -Then to run render and serve the documentation run +Now to actually build the documentation. ```bash -mkdocs serve +./build.sh ``` -The page should be available on this address `http://localhost:8000`. +> [!NOTE] +> You may need to run `chmod +x build.sh` to run it. + + +Finally to serve the documentation: +```bash + mkdocs serve +``` +The page should be available on this address `http://127.0.0.1:8000`. Now whenever you update the markdown in the mkdocs directory, the page will -auto-reload with your changes. Checkout -[mkdocs-material](https://squidfunk.github.io/mkdocs-material/) for more details -on the features that can be used for the site. +auto-reload with your changes, *however* if you are making changes to the API documentation, you must rebuild the documentation. +If you changed just `rst` or `md` files in the `sphinx` directory you can simply run the command inside the `sphinx` directory. + +```bash + sphinx-build -b html -Dbreathe_projects.libhal=../doxygen_output/xml . output +``` +If things changed in the actual code for the documentation, you will need to build the doxygen files as well. +Run the following starting in the root of this repo. + +```bash + doxygen Doxyfile.in + cd sphinx + sphinx-build -b html -Dbreathe_projects.libhal=../doxygen_output/xml . output +``` + +Checkout [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) for more details +on the features that can be used for the static side of this site. + +Checkout [sphinx](https://www.sphinx-doc.org/en/master/) for how to use sphinx at a basic level, [breathe](https://breathe.readthedocs.io/en/latest/) on how to use doxygen directives on how to organize your code inside of sphinx `rst` or `md` files, and finally the [theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/) for theme specific uses for the API documentation. ## Contributing diff --git a/sphinx/_templates/guide_links.html b/sphinx/_templates/guide_links.html index d018d047b..46baed8f9 100644 --- a/sphinx/_templates/guide_links.html +++ b/sphinx/_templates/guide_links.html @@ -1,13 +1,12 @@ {# Displays links to the top-level TOCtree elements, in the header navbar. #}