💄 Clean up a few typos and updated the README

.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
+library_merger_devel.sh

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
 

sphinx/_templates/guide_links.html

@@ -1,13 +1,12 @@
 {# Displays links to the top-level TOCtree elements, in the header navbar. #}
 <nav class="navbar-nav">
     <p class="sidebar-header-items__title" role="heading" aria-level="2" aria-label="{{ _('Site Navigation') }}">
-        {{ _("Site Navigation") }}
     </p>
     <ul class="bd-navbar-elements navbar-nav">
         <li class="nav-item dropdown">
             <button class="btn dropdown-toggle nav-item" type="button" data-bs-toggle="dropdown" aria-expanded="false"
                 aria-controls="pst-nav-more-links">
-                Guides <!--TODO: Workshop this name-->
+                Guides
             </button>
             <ul id="pst-nav-more-links" class="dropdown-menu">
 

sphinx/index.rst

@@ -10,13 +10,12 @@ libhal API documentation
 
 Here you will find an organized list of the interfaces used in libhal. 
 This includes soft drivers which are drivers that are not tied to specific hardware. 
-This will also include utility functions 
-.. TODO: display tree as summary of docs
+This will also include utility functions.
 
 
 
 .. toctree::
-  :caption: hal docs
+  :caption: libhal Docs
   :maxdepth: 5
 
   Libhal Interfaces <libhal/index>