Merge pull request #49 from michaelasprague/dev

Major documentation update

docs/CMakeLists.txt

@@ -13,7 +13,7 @@ if(SPHINX_FOUND)
     set(SPHINX_GENERATOR html)
     file(COPY "conf.py" DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
     file(COPY "_static" DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
-    file(COPY "openfastlogo.jpg" DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
+    #file(COPY "_static/openfastlogo.jpg" DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
     add_custom_target(sphinx
         COMMAND ${SPHINX_EXECUTABLE} -b ${SPHINX_GENERATOR} 
         -c ${CMAKE_CURRENT_BINARY_DIR}

docs/Doxyfile.in

@@ -51,7 +51,7 @@ PROJECT_BRIEF          = "OpenFAST description goes here."
 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
 # the logo to the output directory.
 
-PROJECT_LOGO           = @CMAKE_SOURCE_DIR@/docs/openfastlogo.jpg
+PROJECT_LOGO           = @CMAKE_SOURCE_DIR@/docs/source/openfastlogo.jpg
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
 # into which the generated documentation will be written. If a relative path is

docs/conf.py

@@ -123,6 +123,11 @@ def runDoxygen(sourcfile, doxyfileIn, doxyfileOut):
 # Usually you set "language" from the command line for these cases.
 language = None
 
+#If true, figures, tables and code-blocks are automatically numbered if they 
+#have a caption. At same time, the numref role is enabled. For now, it works 
+#only with the HTML builder and LaTeX builder. Default is False.
+numfig = True
+
 # 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
@@ -148,7 +153,7 @@ def runDoxygen(sourcfile, doxyfileIn, doxyfileOut):
 # a list of builtin themes.
 #
 html_theme = 'sphinx_rtd_theme'
-html_logo = 'openfastlogo.jpg'
+html_logo = '_static/openfastlogo.jpg'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -218,3 +223,11 @@ def runDoxygen(sourcfile, doxyfileIn, doxyfileOut):
      'Miscellaneous'),
 ]
 
+def setup(app):
+    app.add_object_type("confval", "confval",
+                        objname="input file parameter",
+                        indextemplate="pair: %s; input file parameter")
+    app.add_object_type("cmakeval", "cmakeval",
+                        objname="CMake configuration value",
+                        indextemplate="pair: %s; CMake configuration")
+

docs/index.rst

@@ -1,29 +1,75 @@
 .. OpenFAST documentation master file, created by
    sphinx-quickstart on Wed Jan 25 13:52:07 2017.
 
+######################
 OpenFAST Documentation
-======================
+######################
 
-This page is under construction. Our intention is that this page will eventually host
-documents on compiling OpenFAST, theory behind OpenFAST, software-development
-requirements, reporting issues, etc.
+.. only:: html
 
-Please contact `Michael.A.Sprague@NREL.gov <mailto:Michael.A.Sprague@NREL.gov>`_. with questions regarding the OpenFAST
-development plan.
+   :Version: |version|
+   :Date: |today|
 
-For possible bugs, enhancement requests, or code questions, please submit an issues at
-the `OpenFAST Github repository <https://github.com/OpenFAST/OpenFAST>`__.
+Welcome to the documentation site for OpenFAST. 
+
+Overview
+-----------------
+
+OpenFAST is an open-source wind turbine simulation tool that was established in 2017 with the FAST v8 code as its starting point (see :ref:`fast_to_openfast`).  
+OpenFAST is a multi-physics, multi-fidelity tool for simulating the coupled dynamic response of wind turbines.  
+Practically speaking, OpenFAST is the framework (or glue code) that couples computational modules for
+aerodynamics, hydrodynamics for offshore structures, control and electrical system (servo) dynamics, and structural dynamics to enable coupled nonlinear aero-hydro-servo-elastic simulation in the time domain. 
+OpenFAST enables the analysis of a range of wind turbine configurations, including two- or three-blade horizontal-axis rotor, pitch or stall regulation, rigid or teetering hub, upwind or downwind rotor, and lattice or tubular tower. 
+The wind turbine can be modeled on land or offshore on fixed-bottom or floating substructures. 
+
+OpenFAST and its underlying modules are mostly written in Fortran (adhering to the 2003 standard), but modules can be written in C/C++.
+OpenFAST was created with the goal of being a community model, with developers and users from research laboratories, academia, and industry. 
+Our goal is also to ensure that OpenFAST is sustainable software that is well tested and well documented.   
+To that end, we are continually improving the documentation and test coverage for existing code, and we expect that new capabilities will include adequate testing and documentation.
+
+OpenFAST is under development; our team at NREL is now enhancing this documentation and automated unit/regression testing. 
+During this transition period, users can find FAST v8 documentation at https://nwtc.nrel.gov/.
+
+This documentation
+------------------
+
+OpenFAST documentation is built using `Sphinx <http://www.sphinx-doc.org>`_, which uses `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ as its markup language. 
+Online documentation is hosted on `readthedocs <http://openfast.readthedocs.io>`_, where one can choose between documentation generated from the OpenFAST `master` or `dev` github branches  (if viewing this on http://openfast.readthedocs.io click on  ``Read the Docs`` "box" on the lower left corner of the browser screen for options).  
+
+This documentation is divided into two parts:
+
+:ref:`user_guide`
+
+   Directed towards end-users, this part provides detailed documentation
+   regarding installation and usage of the OpenFAST and its underlying modules,
+   as well as theory and verification documentation. 
+   Also included are instructions for using the automated test suite, which 
+   serves as a suite of examples.
+
+:ref:`dev_guide`
+
+   The developer guide is targeted towards users wishing to extend the
+   functionality provided within OpenFAST. Here you will find details
+   regarding the code structure, API supported by various classes, and links to
+   source code documentation extracted using Doxygen.
+
+**Note:** If viewing this on http://openfast.readthedocs.io,  one can get this documentation in PDF form via ``Read the Docs`` "box" on the lower left corner of the browser screen.  
 
-Users may find the established FAST8 through the NWTC Information Portal:
-https://nwtc.nrel.gov/
 
 .. toctree::
-   :maxdepth: 2
-
-   OpenFAST Github Organization Page <https://github.com/OpenFAST>
-   OpenFAST Github Repository <https://github.com/OpenFAST/OpenFAST>
-   Installing OpenFAST  <source/install.rst>
-   Testing OpenFAST  <source/test.rst>
-   Source Code Documentation <source/code.rst>
-   Building this Documentation Locally <source/build_doc.rst>
-   FAST to OpenFAST transition <source/fast_to_openfast.rst>
+   :numbered:
+   :maxdepth: 1
+
+   source/get_started.rst
+   source/install/index.rst
+   source/testing/index.rst
+   source/user/index.rst
+   source/dev/index.rst
+   source/links.rst
+   source/license.rst
+   source/help.rst
+   source/acknowledgements.rst
+
+   Nightly Testing Results <http://my.cdash.org/index.php?project=OpenFAST>
+   github.com Repository <https://github.com/openfast/openfast>
+

docs/source/acknowledgements.rst

@@ -0,0 +1,17 @@
+.. _acknowledgements:
+
+Acknowledgements
+================
+
+This software is developed and maintained by researchers at the `National Renewable Energy Laboratory <https://www.nrel.gov>`_ with funding from U.S.     
+Department of Energy (DOE) Wind Energy Technology Office through the `Atmosphere to electrons (A2e) <https://a2e.energy.gov>`_ research initiative.
+
+NREL gratefully acknowledges development contributions from the following organizations:
+
+* Envision Energy USA, Ltd
+
+* Brigham Young University
+
+NREL gratefully acknowledges additional development support through an
+`Intel® Parallel Computing Center (IPCC) <https://software.intel.com/en-us/ipcc>`_
+

docs/source/build_doc.rst → docs/source/dev/build_doc.rst

@@ -1,4 +1,6 @@
-Building this Documentation Locally
+.. _build_doc:
+
+Building this documentation locally
 ===================================
 
 This document describes how to build the OpenFAST documentation on your local   machine.  Documentation is automatically built and updated on readthedocs when  new material is pushed to the github repo. However, while developing            documentation, one should build locally to see changes quickly, and without the need to push your changes to see them on readthedocs.

docs/source/dev/dev_phil.rst

@@ -0,0 +1,28 @@
+.. _dev_philosophy:
+
+OpenFAST-development philosophy
+================================
+
+**Under construction**
+
+OpenFAST and its underlying modules are mostly written in Fortran (adhering to the 2003 standard), but modules can be written in C/C++. 
+OpenFAST was created with the goal of being a community model with developers and users from research laboratories, academia, and industry. 
+
+**Our goal as developers is to ensure that OpenFAST is sustainable software that is well tested and well documented.**
+To that end, we are continually improving the documentation and test coverage for existing code, and we expect that new capabilities will include adequate testing and documentation.
+
+Moving forward, we have the following guidance for developers:
+
+- When fixing a bug, first introduce a unit test that exposes the bug, fix the bug, and submit a Pull Request.  
+  See :numref:`testing` and :numref:`github_workflow`.
+
+- When adding a new feature, create appropriate automated unit and regression tests as described in :numref:`testing`.  
+  The objective is to create a GitHub pull request that provides adequate verification and validation such that the NREL OpenFAST developer team
+  can merge the pull request with confidence that the new feature is "correct" and supports our goal of self-sustaining software.
+  See :numref:`pull_requests` for detailed information on submitting a pull request.
+
+- If a code modification affects regression-test results in an expected manner, work with the NREL OpenFAST developer team to upgrade the regression-test suite via a ``New Issue`` on the `github.com <https://github.com/openfast/openfast/issues>`_ repository.
+
+- While OpenFAST developer documentation is being enhanced here, developers are encouraged to consult the legacy FAST v8 `Programmer's Handbook <https://nwtc.nrel.gov/system/files/ProgrammingHandbook_Mod20130717.pdf>`_.
+
+

docs/source/dev/doxy_doc.rst

@@ -0,0 +1,7 @@
+Doxygen API documentation
+=========================
+
+  * `Main Page <../../html/index.html>`_
+  * `Index of Classes <../../html/classes.html>`_
+  * `Files <../../html/files.html>`_
+

docs/source/dev/github_workflow.rst

@@ -0,0 +1,70 @@
+.. _github_workflow:
+
+Workflow for interacting with the OpenFAST github.com repo
+==========================================================
+
+OpenFAST development should follow "Git Flow" when interacting with the github repository.
+Git Flow is a git workflow outlining safe methods of pushing and pulling commits
+to a shared repository. Maintaining Git Flow is critical to prevent remote changes
+from blocking your local development.
+
+Git Flow
+--------
+
+The Git Flow process is well defined and adopted throughout the software development
+community. It is detailed nicely `here <http://nvie.com/posts/a-successful-git-branching-model>`__
+and the chart below provides a high level perspective.
+
+.. image:: ../../_static/GitFlowFeatureBranches.png
+    :align: center
+
+Reference: http://nvie.com/posts/a-successful-git-branching-model
+
+
+OpenFAST Specific Git Flow
+--------------------------
+
+It is important to consider how your current work will be affected by other developer's
+commits and how your commits will affect other developers. On public branches, avoid using
+`git rebase <https://git-scm.com/book/en/v2/Git-Branching-Rebasing>`__
+and never `force push <https://git-scm.com/docs/git-push#git-push---force>`__. 
+
+In OpenFAST development, the typical workflow follows this procedure
+
+1. Fork OpenFAST/OpenFAST on GitHub
+
+2. Clone your new fork: ``git clone https://github.com/youruser/OpenFAST``
+
+3. Create a feature branch for active development: ``git branch feature/a_great_feature``
+
+4. Add new development on feature/a_great_feature: ``git push/pull``
+
+5. Update your feature branch with OpenFAST/dev: ``git pull https://github.com/OpenFAST/OpenFAST dev; git push``
+
+6. Create a GitHub pull request to merge ``youruser/OpenFAST/feature/a_great_feature`` into ``OpenFAST/OpenFAST/dev``
+
+
+.. _pull_requests:
+
+Pull Requests
+-------------
+
+New pull requests should contain
+
+- A description of the need for modifications
+
+  - If the pull request fixes a bug, the accompanying GitHub issue should be referenced
+
+- A highlight of the work implemented
+- Regression test results
+
+  - If all tests pass, the summary print out should be provided
+  - If any tests fail, an explanation of the failing cases and supporting data like plots should be included 
+
+- Updated unit tests, if applicable
+- Updated documentation in applicable sections ready for compilation and deployment to `readthedocs <http://openfast.readthedocs.io>`__.
+- A review request from a specific member of the NREL OpenFAST team
+
+
+
+

docs/source/dev/index.rst

@@ -0,0 +1,19 @@
+.. _dev_guide:
+
+Developer Documentation
+=======================
+
+**Under construction.**
+
+This section of OpenFAST documentation is directed at developers, e.g., those who will be adding new modules, improving existing modules, fixing bugs, etc.  The OpenFAST software repository is on `github.com <https://github.com/openfast/openfast>`_, and we ask that developers make contributions through "pull requests" as described in :numref:`github_workflow`.  
+OpenFAST documentation is posted on `readthedocs.com <http://openfast.readthedocs.io/>`_; that documentation is generated automatically from both the ``master`` and ``dev`` branches on `github.com <https://github.com/openfast/openfast>`_ whenever new material is committed.  
+However, documentation can be generated on a local machine as described in :numref:`build_doc`.  Note that on the `readthedocs.com <http://openfast.readthedocs.io/>`_ site, one can build a PDF of the documentation (click on lower left corner for options).
+
+.. toctree::
+   :maxdepth: 1
+
+   dev_phil.rst
+   github_workflow.rst
+   build_doc.rst
+   doxy_doc.rst
+

docs/source/get_started.rst

@@ -0,0 +1,41 @@
+.. _get_started:
+
+Getting Started
+===============
+
+**Get the code:**
+
+OpenFAST can be cloned (i.e., downloaded) from its `Github Repository <https:// github.com/OpenFAST/OpenFAST>`_, e.g., from the command line:
+::
+
+    git clone https://github.com/OpenFAST/OpenFAST.git
+
+It can also be downloaded directly from https://github.com/OpenFAST/OpenFAST.git.
+
+**Compile the code:**
+
+See :ref:`installation`, for installation instructions (including dependency    requirements) for CMake, Spack, and Visual Studio and for multiple platforms    (Linux, Mac, Windows).
+As an example, from the command line in a Mac or Linux environment:
+::
+
+    cd OpenFAST
+    mkdir build && cd build
+    cmake ../
+    make
+
+Note that one can see all of the `make` targets via
+::
+
+    make help
+
+
+**Use the code:**
+
+See :ref:`user_guide`, which is under construction.
+In the interim, users may refer to the FAST v8 documentation at https://nwtc.nrel.gov/.
+
+**Develop the code:**
+
+See :ref:`dev_guide`, which is under construction.
+In the interim, developers may consult the FAST v8 `Programmer's Handbook <https://nwtc.nrel.gov/system/files/ProgrammingHandbook_Mod20130717.pdf>`_.
+

docs/source/help.rst

@@ -0,0 +1,15 @@
+.. _help:
+
+Getting Help
+============
+
+For possible bugs, enhancement requests, or code questions, please submit an    issue at
+the `OpenFAST Github repository <https://github.com/OpenFAST/OpenFAST>`_.
+
+For OpenFAST usage questions, users should consider the `FAST Forum <https://   wind.nrel.gov/forum/wind/>`_, which provides a large 10+ year legacy of FAST-related Q&A; the forum's search        functionality should be used before posting questions to either github issues or the forum.
+
+Users may find the established FAST v8 through the NWTC Information Portal:
+https://nwtc.nrel.gov/
+
+Please contact `Michael.A.Sprague@NREL.gov <mailto:Michael.A.Sprague@NREL.      gov>`_. with questions regarding the OpenFAST development plan or how to contribute.
+

docs/source/install/get_openfast.rst

@@ -0,0 +1,15 @@
+.. _get_openfast:
+
+Obtaining the OpenFAST source code
+==================================
+
+OpenFAST can be cloned (i.e., downloaded) from its `Github Repository <https:// github.com/openfast/openfast>`_.
+For example, from a command line:
+
+::
+
+    git clone https://github.com/OpenFAST/OpenFAST.git
+
+It can also be downloaded directly from https://github.com/OpenFAST/OpenFAST.git.
+
+