move scripts to source folder, typos fixes, cleanup

docs/conf.py

@@ -1,57 +1,179 @@
-# Configuration file for the Sphinx documentation builder.
 #
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Path setup --------------------------------------------------------------
-
+# ROSCO toolbox documentation build configuration file, created by
+# sphinx-quickstart on Fri Jan 12 14:22:01 2018.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
-
-# -- Project information -----------------------------------------------------
+import os
+import sys
+import subprocess
 
-project = u'ROSCO_toolbox'
-copyright = u'2020, National Renewable Energy Laboratory'
-author = u'ROSCO development team'
 
-# The full version, including alpha/beta/rc tags
-release = u'2.1.1'
+cwd = os.getcwd()
+roscopath = os.path.dirname(cwd)
+sys.path.insert(0, roscopath)
 
-
-# -- General configuration ---------------------------------------------------
+# -- General configuration ------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.autodoc",
+    "readthedocs_ext.readthedocs",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinxcontrib.bibtex",
 ]
 
+autosummary_generate = True
+
+# Napoleon settings
+napoleon_google_docstring = True
+napoleon_include_init_with_doc = True
+
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
-# -- Options for HTML output -------------------------------------------------
+# General information about the project.
+project = "ROSCO toolbox"
+copyright = "2020, NREL"
+author = "ROSCO developers"
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
 #
-html_theme = 'alabaster'
+version = "2.1.1"
+release = "2.1.1"
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "_templates"]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+html_theme = "alabaster"
+# html_static_path = ["_static/custom.css"]
+html_theme_options = {
+    # "logo": "logo.png",
+    # "logo_name": True,
+    "badge_branch": "develop",
+    "codecov_button": True,
+    "fixed_sidebar": True,
+    "github_user": "NREL",
+    "github_repo": "ROSCO toolbox",
+    "sidebar_width": "375px",
+    "page_width": "75%",
+    "show_relbars": True,
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = [os.path.join('source', '_static')]
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# This is required for the alabaster theme
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
+html_sidebars = {"**": ["about.html", "navigation.html", "searchbox.html"]}
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "ROSCOdoc"
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+# latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#
+# 'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#
+# 'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#
+# 'preamble': '',
+
+# Latex figure (float) alignment
+#
+# 'figure_align': 'htbp',
+# }
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+# latex_documents = [
+#     (master_doc, 'ROSCO_toolbox.tex', 'ROSCO toolbox Documentation',
+#      'NREL', 'manual'),
+# ]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [(master_doc, "ROSCO toolbox", "ROSCO toolbox Documentation", [author], 1)]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (
+        master_doc,
+        "ROSCO toolbox",
+        "ROSCO toolbox Documentation",
+        author,
+        "ROSCO toolbox",
+        "A reference open source controller framework for wind turbine applications",
+        "Miscellaneous",
+    ),
+]
+
+
+# -- Options for autodoc --------------------------------------------------
+
+autodoc_member_order = "groupwise"

docs/index.rst

@@ -1,5 +1,11 @@
-.. ROSCO_toolbox documentation master file, created by
-   sphinx-quickstart on Mon Aug  3 22:46:52 2020.
+.. toctree::
+   :hidden:
+   :glob:
+   :titlesonly:
+
+   source/compiling.rst
+   source/generating.rst
+
 
 ROSCO toolbox documentation
 ===========================
@@ -10,24 +16,26 @@ ROSCO toolbox documentation
 
 NREL's Reference OpenSource Controller (ROSCO) toolbox for wind turbine applications is a toolbox designed to ease controller implementation for the wind turbine researcher. The purpose of these documents is to provide information for the use of the ROSCO related toolchain. 
 
-Standard Use:
-----------
-For the standard use case in OpenFAST, ROSCO will need to be compiled. This is made possible via the instructions found in the :ref:`compiling` instructions. Once the controller is compiled, the turbine model should point to the compiled binary. In OpenFAST, this is ensured by changing the `DLL_FileName` parameter in the ServoDyn input file. 
+Standard Use
+-------------
+For the standard use case in OpenFAST, ROSCO will need to be compiled. This is made possible via the instructions found in the :ref:`compiling` instructions. Once the controller is compiled, the turbine model should point to the compiled binary. In OpenFAST, this is ensured by changing the :code:`DLL_FileName` parameter in the ServoDyn input file. 
 
-Additionally, an input file is needed for the ROSCO controller. Though the controller only needs to be compiled once, each individual turbine and controller tuning requires an input file. This input file is generically dubbed "DISCON.IN''. In OpenFAST, the `DLL_InFile` parameter should be set to point to the desired input file. The ROSCO toolbox is used to automatically generate the input file. These instructions are provided in the instructions for :ref:`generate_discon`.
+Additionally, an input file is needed for the ROSCO controller. Though the controller only needs to be compiled once, each individual turbine and controller tuning requires an input file. This input file is generically dubbed "DISCON.IN''. In OpenFAST, the :code:`DLL_InFile` parameter should be set to point to the desired input file. The ROSCO toolbox is used to automatically generate the input file. These instructions are provided in the instructions for :ref:`generate_discon`.
+
+License
+-------
 
-**Documentation Directory**
-.. toctree::
-   :maxdepth: 2
 
-   compiling.rst
-   generating.rst
+Copyright 2020 NREL
 
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
 
+   http://www.apache.org/licenses/LICENSE-2.0
 
-.. Indices and tables
-.. ==================
-.. 
-.. * :ref:`genindex`
-.. * :ref:`modindex`
-.. * :ref:`search`
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

docs/requirements.txt

@@ -0,0 +1,6 @@
+# Requirements list for floris documentation
+readthedocs-sphinx-ext
+Sphinx>=2.0
+sphinxcontrib-napoleon
+sphinxcontrib-bibtex
+-r ../requirements.txt

docs/compiling.rst → docs/source/compiling.rst

@@ -2,37 +2,51 @@
 
 Compiling ROSCO
 =================
-The standard ROSCO controller is based in Fortran and must be compiled. This code can be found at: https://github.com/NREL/ROSCO. Of course, the advanced user can compile the downloaded code using their own desired methods (e.g. Visual Studio). Otherwise, a few of the more common compiling methods are detailed on this page. The most recent tagged version releases are `available for download <https://github.com/NREL/ROSCO/tags>`_. If one wishes to download the code via the command line, we provide two supported options. For non-developers (those not interested in modifying the source code), the controller can be downloaded via Anaconda. For developers, CMake can be used to compile the Fortran code. Using CMake is generally a simple and straightforward process for Mac/Linux users, however, the process of compiling using CMake and MinGW is possible on Windows, but can produce complications if not done carefully. 
+The standard ROSCO controller is based in Fortran and must be compiled. This code can be found at: https://github.com/NREL/ROSCO. Of course, the advanced user can compile the downloaded code using their own desired methods (e.g. Visual Studio). Otherwise, a few of the more common compiling methods are detailed on this page. Additionally, the most recent tagged version releases are `available for download <https://github.com/NREL/ROSCO/tags>`_. 
+
+If one wishes to download the code via the command line, we provide two supported options. For non-developers (those not interested in modifying the source code), the controller can be downloaded via Anaconda. For developers, CMake can be used to compile the Fortran code. Using CMake is generally a simple and straightforward process for Mac/Linux users, however, the process of compiling using CMake and MinGW is possible on Windows, but can produce complications if not done carefully. 
 
 Anaconda for non-developers:
-----------------------------
-For users familiar with Anaconda_, ROSCO is available through the conda-forge channel. In order to download the compiled, most recent version release, one can simply create a new anaconda virtual environment using (skip this step if you are already in a desired virtual environment with the conda-forge channel added): 
+------------------------------------
+For users familiar with Anaconda_, ROSCO is available through the conda-forge channel. In order to download the compiled, most recent version release, from an anaconda powershell (Windows) or terminal (Mac/Linux) window, one can create a new anaconda virtual environment: 
 ::
+
     conda config --add channels conda-forge
     conda create -y --name ROSCO-env
     conda activate ROSCO-env
 
-Navigate to your desired folder to save the compiled binary using:
+navigate to your desired folder to save the compiled binary using:
 ::
+
     cd <my_desired_folder>
-and download the controller using from an anaconda powershell (Windows) or terminal (Mac/Linux):
+    
+and download the controller:
 ::
+
     conda install -y ROSCO
+
 This will download a compiled ROSCO binary file into the default filepath for any dynamic libraries downloaded via anaconda while in the ROSCO-env. This can be copied to your desired folder using:
 ::
+
     cp $CONDA_PREFIX/lib/libdiscon.* .
 
 CMake for developers:
---------------------
+-------------------------------
 CMake_ provides a straightforward option for many users, particularly those on a Mac or Linux. ROSCO can be compiled by first cloning the source code from git using:
 ::
+
     git clone https://github.com/NREL/ROSCO.git
+
 And then compiling using CMake:
 ::
+
     cd ROSCO
     mkdir build
     cd build
     cmake ..
     make
 
-This will generate a file titled `libdiscon.*` in the current directory. 
+This will generate a file titled :code:`libdiscon.*` in the current directory. 
+
+.. _Anaconda: https://www.anaconda.com/
+.. _CMake: https://cmake.org/