From 729f4b070882f2c595650e991bd4b458098eeace Mon Sep 17 00:00:00 2001 From: genevievestarke <103534902+genevievestarke@users.noreply.github.com> Date: Tue, 27 Feb 2024 15:37:35 -0700 Subject: [PATCH] Fixing documentation build (#30) * Fixing documentation build * remove main from deploy-pages.yaml; remote unused _templates. * Typo fixes in docs. --------- Co-authored-by: misi9170 --- .github/workflows/deploy-pages.yaml | 1 - docs/_config.yml | 36 +----------- docs/_templates/custom-class-template.rst | 34 ----------- docs/_templates/custom-module-template.rst | 66 ---------------------- docs/examples.md | 6 +- docs/install_instructions.md | 6 +- docs/interfaces.md | 4 +- docs/intro.md | 2 +- setup.py | 8 +-- 9 files changed, 14 insertions(+), 149 deletions(-) delete mode 100644 docs/_templates/custom-class-template.rst delete mode 100644 docs/_templates/custom-module-template.rst diff --git a/.github/workflows/deploy-pages.yaml b/.github/workflows/deploy-pages.yaml index 09eb4c1e..8ce1fce9 100644 --- a/.github/workflows/deploy-pages.yaml +++ b/.github/workflows/deploy-pages.yaml @@ -4,7 +4,6 @@ on: push: branches: - develop - - main paths: - docs/** diff --git a/docs/_config.yml b/docs/_config.yml index e63c6699..288485ae 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -4,7 +4,7 @@ title: Wind Hybrid Open Controller author: National Renewable Energy Laboratory # logo: herc.png -copyright: '2023' +copyright: '2024' only_build_toc_files: false # Force re-execution of notebooks on each build. @@ -36,37 +36,3 @@ html: google_analytics_id: G-BJZY823DHG -# Sphinx for API doc generation -sphinx: - extra_extensions: - - 'sphinx.ext.autodoc' - - 'sphinx.ext.autosummary' - - 'sphinx.ext.viewcode' - - 'sphinx_autodoc_typehints' - - 'sphinxcontrib.autoyaml' - - 'sphinx.ext.napoleon' # Formats google and numpy docstring styles - - 'sphinxcontrib.mermaid' - config: - html_theme: sphinx_book_theme - templates_path: - - '_templates' - language: 'python' - autoyaml_level: 3 - autosummary_generate: true - - # Autodoc config reference - # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration - autodoc_default_options: - members: true - member-order: bysource - undoc-members: true - private-members: true - # special-members: true - # inherited-members - # show-inheritance - # ignore-module-all - # imported-members: true - # exclude-members - # class-doc-from - # no-value - autodoc_typehints: both diff --git a/docs/_templates/custom-class-template.rst b/docs/_templates/custom-class-template.rst deleted file mode 100644 index f73eda50..00000000 --- a/docs/_templates/custom-class-template.rst +++ /dev/null @@ -1,34 +0,0 @@ -{{ fullname | escape | underline}} - -.. currentmodule:: {{ module }} - -.. autoclass:: {{ objname }} - :members: - :show-inheritance: - :inherited-members: - :special-members: __call__, __add__, __mul__ - - {% block methods %} - {% if methods %} - .. rubric:: {{ _('Methods') }} - - .. autosummary:: - :nosignatures: - {% for item in methods %} - {%- if not item.startswith('_') %} - ~{{ name }}.{{ item }} - {%- endif -%} - {%- endfor %} - {% endif %} - {% endblock %} - - {% block attributes %} - {% if attributes %} - .. rubric:: {{ _('Attributes') }} - - .. autosummary:: - {% for item in attributes %} - ~{{ name }}.{{ item }} - {%- endfor %} - {% endif %} - {% endblock %} diff --git a/docs/_templates/custom-module-template.rst b/docs/_templates/custom-module-template.rst deleted file mode 100644 index d066d0e4..00000000 --- a/docs/_templates/custom-module-template.rst +++ /dev/null @@ -1,66 +0,0 @@ -{{ fullname | escape | underline}} - -.. automodule:: {{ fullname }} - - {% block attributes %} - {% if attributes %} - .. rubric:: Module attributes - - .. autosummary:: - :toctree: - {% for item in attributes %} - {{ item }} - {%- endfor %} - {% endif %} - {% endblock %} - - {% block functions %} - {% if functions %} - .. rubric:: {{ _('Functions') }} - - .. autosummary:: - :toctree: - :nosignatures: - {% for item in functions %} - {{ item }} - {%- endfor %} - {% endif %} - {% endblock %} - - {% block classes %} - {% if classes %} - .. rubric:: {{ _('Classes') }} - - .. autosummary:: - :toctree: - :template: custom-class-template.rst - :nosignatures: - {% for item in classes %} - {{ item }} - {%- endfor %} - {% endif %} - {% endblock %} - - {% block exceptions %} - {% if exceptions %} - .. rubric:: {{ _('Exceptions') }} - - .. autosummary:: - :toctree: - {% for item in exceptions %} - {{ item }} - {%- endfor %} - {% endif %} - {% endblock %} - -{% block modules %} -{% if modules %} -.. autosummary:: - :toctree: - :template: custom-module-template.rst - :recursive: -{% for item in modules %} - {{ item }} -{%- endfor %} -{% endif %} -{% endblock %} diff --git a/docs/examples.md b/docs/examples.md index 8110eb56..119217a4 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,6 +1,6 @@ # Examples -The `examples` subdirectoy contains a series of examples that can be run to test the functionality +The `examples` subdirectory contains a series of examples that can be run to test the functionality of certain controllers and interfaces. ### lookup-based_wake_steering_florisstandin @@ -11,9 +11,9 @@ examples/lookup-based_wake_steering_florisstandin and then run the following. python construct_yaw_offsets.py ``` -Not that, currently, contruct_yaw_offsets.py requires FLORIS version 3, whereas the rest of the +Not that, currently, construct_yaw_offsets.py requires FLORIS version 3, whereas the rest of the example requires FLORIS version 4. As a result, we provide the generated offsets in -yaw_offesets.pkl. To avoid regenerating yaw_offsets.pkl (and therefore avoid the current need for +yaw_offsets.pkl. To avoid regenerating yaw_offsets.pkl (and therefore avoid the current need for floris v3), set `optimize_yaw_offsets = False` at the beginning of construct_yaw_offsets.py before running. diff --git a/docs/install_instructions.md b/docs/install_instructions.md index ec284b0b..c0c1acd1 100644 --- a/docs/install_instructions.md +++ b/docs/install_instructions.md @@ -3,9 +3,9 @@ WHOC is _not_ designed to be used as a stand-alone package. Most likely, you'll want to add WHOC to an existing conda environment that contains your simulation testbed, such as [Hercules](https://github.com/NREL/hercules). -For example, see the [Hercules installation instuctions](\ -https://nrel.github.io/hercules/install_instructions.html) for how to set up -an appropriate conda environment. +For example, see the +[Hercules installation instructions](https://nrel.github.io/hercules/install_instructions.html) +for how to set up an appropriate conda environment. ## General users diff --git a/docs/interfaces.md b/docs/interfaces.md index a85035df..1ae11db9 100644 --- a/docs/interfaces.md +++ b/docs/interfaces.md @@ -5,14 +5,14 @@ WHOC with various simulation platforms and other repositories. Each controller run will require an `interface`, which is an instantiated object of a class in this library. All interface classes should inherit from `InterfaceBase`, which can be found n interface_base.py, and should implement three methods: -- `get_measurements()`: Recieve measurements from simulation assets and +- `get_measurements()`: Receive measurements from simulation assets and organize into a dictionary that the calling controller can utilize. Optionally, receives a large dictionary (for example, the Hercules `main_dict`), from which useable measurements can be extracted/repackaged for easy use in the controller. - `check_controls()`: Check that the keys in `controls_dict` are viable for the receiving plant. - `send_controls()`: Send controls to the simulation assets. Controls are -created as specific keyword arguements, which match those controls generated +created as specific keyword arguments, which match those controls generated by the calling controller. Optionally, receives a large dictionary (for example, the Hercules `main_dict`), which can be written to and returned with controls as needed. diff --git a/docs/intro.md b/docs/intro.md index 8cbe1f98..689acbd8 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -23,7 +23,7 @@ found in controllers.md. The `interface` object handles communications with the plant simulator, allowing WHOC to be used with various simulation platforms (e.g. Hercules, FAST.Farm) while keeping the controllers agnostic to the simulation platform -and the boilderplate code needed to handle different platforms. `interface` +and the boilerplate code needed to handle different platforms. `interface` objects should inherit from `InterfaceBase`. More information can be found in interfaces.md. diff --git a/setup.py b/setup.py index 9042c886..803130a9 100644 --- a/setup.py +++ b/setup.py @@ -57,11 +57,11 @@ # What packages are optional? EXTRAS = { "docs": { - "jupyter-book<=0.13.3", + "jupyter-book", "sphinx-book-theme", - "sphinx-autodoc-typehints", - "sphinxcontrib-autoyaml", - "sphinxcontrib.mermaid", + # "sphinx-autodoc-typehints", + # "sphinxcontrib-autoyaml", + # "sphinxcontrib.mermaid", }, "develop": { "pytest",