Add docs outline

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,108 @@
+# 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 --------------------------------------------------------------
+
+# 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
+
+cwd = os.getcwd()
+weispath = os.path.dirname(cwd)
+sys.path.insert(0, weispath)
+sys.path.insert(0, os.path.abspath('./_exts'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'WEIS'
+copyright = '2020, NREL WEIS Team'
+author = 'NREL WEIS Team'
+
+# The full version, including alpha/beta/rc tags
+release = '2.0'
+
+
+# -- 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.autodoc',
+              'sphinx.ext.coverage',
+              'sphinx.ext.napoleon',
+              'sphinx.ext.mathjax',
+              'sphinx.ext.viewcode',
+              'numpydoc',
+              'sphinx.ext.autosummary',
+              'sphinxcontrib.bibtex',
+              'sphinx.ext.intersphinx',
+              'sphinx_rtd_theme',
+              # 'autoapi.extension',
+              # 'embed-n2',
+]
+
+
+# Numbering figures in HTML format (always numbered in latex)
+numfig = True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The master toctree document.
+master_doc = 'index'
+
+# 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']
+
+# TODO : need to set these options correctly.
+# Right now we list out all OpenMDAO methods we don't want to document.
+autodoc_default_options = {
+    'member-order': 'bysource',
+    'undoc-members': True,
+    'exclude-members': '__weakref__, add_constraint, add_design_var, add_discrete_input, add_discrete_output, add_input, add_objective, add_output, add_recorder, add_response, check_config, cleanup, compute, compute_jacvec_product, compute_partials, convert2units, declare_coloring, declare_partials, get_approx_coloring_fname, get_constraints, get_design_vars, get_linear_vectors, get_nonlinear_vectors, get_objectives, get_responses, initialize, is_active, list_inputs, list_outputs, reconfigure, record_iteration, resetup, run_apply_linear, run_apply_nonlinear, run_linearize, run_solve_linear, run_solve_nonlinear, set_check_partial_options, set_initial_values, set_solver_print, setup, system_iter, use_fixed_coloring, add_subsystem, approx_totals, compute_sys_graph, configure, connect, guess_nonlinear, promotes, set_order',
+}
+
+# -- Options for HTML output ----------------------------------------------
+
+# html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static/custom.css']
+html_theme_options = {
+    # "logo": "logo.png",
+    # "logo_name": True,
+    # "badge_branch": "IEAontology4all",
+    # "codecov_button": True,
+    # "fixed_sidebar": True,
+    # "github_user": "WEIS",
+    # "github_repo": "WEIS",
+    # "sidebar_width": '220px',
+    # "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 = [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'        
+    ]
+}

docs/how_to_contribute_code.rst

@@ -0,0 +1,37 @@
+.. how_to_contribute_code:
+
+How to contribute code to WISDEM
+================================
+
+.. note::
+  This section will be expanded in the future.
+
+WISDEM is an open-source tool, thus we welcome users to submit additions or fixes to the code to make it better for everybody.
+
+Issues
+------
+If you have an issue with WISDEM, a bug to report, or a feature to request, please submit an issue on the GitHub repository.
+This lets other users know about the issue.
+If you are comfortable fixing the issue, please do so and submit a pull request.
+
+Documentation
+-------------
+When you add or modify code, make sure to provide relevant documentation that explains the new code.
+This should be done in code via comments, but also in the Sphinx documentation as well if you add a new feature or capability.
+Look at the .rst files in the `docs` section of the repo or click on `view source` on any of the doc pages to see some examples.
+
+Testing
+-------
+When you add code or functionality, add tests that cover the new or modified code.
+These may be units tests for individual components or regression tests for entire models that use the new functionality.
+
+Each discipline sub-directory contains tests in the `test` folder.
+For example, `wisdem/test/test_ccblade` hosts the tests for CCBlade within WISDEM.
+Look at `test_ccblade.py` within that folder for a simple unit test that you can mimic when you add new components.
+
+Pull requests
+-------------
+Once you have added or modified code, submit a pull request via the GitHub interface.
+This will automatically go through all of the tests in the repo to make sure everything is functioning properly.
+This also automatically does a coverage test to ensure that any added code is covered in a test.
+The main developers of WISDEM will then merge in the request or provide feedback on how to improve the contribution.

docs/how_to_write_docs.rst

@@ -0,0 +1,142 @@
+.. how_to_write_docs:
+
+How to write docs for WEIS code
+===============================
+
+.. TODO: expand this
+
+Introduction
+------------
+This page describes how to add, improve, and update any of the WEIS documentation.
+The WEIS documentation can be divided into two categories, a documentation for WEIS submodules, and then WEIS usage documentation, tutorials and guides.
+
+
+Getting started with the docs
+-----------------------------
+
+When adding or updating the documentation please try to follow the these guidelines:
+
+* files and folders should follow the existing naming convention
+* images, figures and files should be placed in specific folders
+
+To update the repo, you need to commit and push your changes. Use the following commands, but with a more descriptive commit message::
+
+    git commit -am "Updated docs"
+    git push
+
+Sphinx and rst
+--------------
+In all cases documentation is generated using the `Sphinx <http://www.sphinx-doc.org/en/master/index.html>`_ documentation generator.
+
+The source files or the documentation itself is written in `reStructuredText <http://docutils.sourceforge.net/rst.html>`_. A primer on the ``rst`` syntax can be found `here <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_. In general http://www.sphinx-doc.org is very helpful for syntax and examples.
+
+.. NOTE::
+    When viewing the documentation in a browser you can always view the source by clicking the **Show Source** link. This is also a great way of getting examples.
+
+The sphinx system uses Makefiles to generate the documentation from the source ``.rst`` files.
+
+In any case, to build the documentation, navigate to the ``docs`` folder and run the following command from the command line::
+
+    make html
+
+
+
+General guidelines for formatting
+---------------------------------
+
+Headings
+~~~~~~~~
+When contributing to any documentation please use the following character for heading levels::
+
+    Sample heading 1
+    ================
+
+    Sample heading 2
+    ----------------
+
+    Sample heading 3
+    ~~~~~~~~~~~~~~~~
+
+    Sample heading 4
+    ****************
+
+
+.. NOTE::
+    Make sure the character underlines the entire heading or Sphinx will generate warnings when building.
+
+Tables
+~~~~~~
+Tables can be difficult to get "right" in html and especially when compiled to LaTeX. Using the simple version of tables often leads to imbalanced column widths and building LaTeX documents often results in bad tables. To try to mitigate this issue another table type should be used::
+
+    .. tabularcolumns:: |>{\raggedright\arraybackslash}\X{1}{5}|>{\raggedright\arraybackslash}\X{1}{5}|>{\raggedright\arraybackslash}\X{3}{5}|
+
+    .. list-table:: Demo table title
+        :widths: 15 20 65
+        :header-rows: 1
+
+        * - Col 1
+          - Col 2
+          - Col 3
+
+        * - Entry 1
+          - Entry 2
+          - Entry 3
+
+.. NOTE::
+
+    - ``tabularcolumns``: Controls how LaTeX generates the following table. The ``widths`` keyword is overridden/omitted for LaTeX when this keyword is specified. The \X{1}{5} is this column width ratio.
+    - ``widths``: keyword represents columns widths in percentages.
+    - ``header-rows`` keyword specifies how many rows are made bold and shaded
+
+
+The code above generates the following table
+
+.. list-table:: Demo table title
+    :widths: 15 20 65
+    :header-rows: 1
+
+    * - Col 1
+      - Col 2
+      - Col 3
+
+    * - Entry 1
+      - Entry 2
+      - Entry 3
+
+
+
+Where should files related to documentation live?
+-------------------------------------------------
+Add figures and small files to the ``docs`` folder then embed them as desired
+in the `.rst` files.
+For larger files, host them elsewhere and link to them from the docs.
+
+
+Where should you contribute docs to?
+------------------------------------
+As you begin to determine if you should write a doc page, first search for relevant
+entries to make sure you don't duplicate something that already exists.
+You can then judge if your contribution should be in its own doc page or if it
+should be added to an existing page.
+Make sure to think logically about where the information you prepared should live so
+it is intuitive for other people, especially people just starting out.
+
+Once you have added your `.rst` file in the repo in a logical place within the file
+structure, also update the table of contents in the other relevant `.rst` files as
+needed.
+This ensures that your contributions can be easily found.
+
+How to convert existing docs
+----------------------------
+If you already have something typed up, either in Latex, a basic text file, or another
+format, it's usually pretty straightforward to convert this to rst.
+`Pandoc <https://pandoc.org/demos.html>`__ is a helpful automated tool that converts
+text files near seamlessly.
+
+How to request doc creation
+---------------------------
+If you think the docs should be modified or expanded, create an issue on the GitHub documentation repository.
+Do this by going to the `WEIS repo <https://github.com/WISDEM/WEIS/>`__ then click on Issues on the lefthand side of the page.
+There you can see current requests for doc additions as well as adding your own.
+Feel free to add any issue for any type of doc and members of the WEIS development team can determine how to approach it.
+Assign someone or a few people to the issue who you think would be a good fit for that doc.

docs/how_weis_works.rst

@@ -0,0 +1,6 @@
+.. _documentation-label:
+
+How WEIS works
+--------------
+
+This page is in progress.

docs/index.rst

@@ -0,0 +1,38 @@
+WEIS Documentation
+==================
+
+WEIS, Wind Energy with Integrated Servo-control, performs multifidelity co-design of wind turbines.
+WEIS is a framework that combines multiple NREL-developed tools to enable design optimization of floating offshore wind turbines.
+
+Important Links:
+
+- `Source Code Repository <https://github.com/WISDEM/WEIS>`_ 
+
+.. This images is a placeholder, feel free to replace. -JPJ
+.. figure:: /images/WEIS.png
+
+Using WEIS
+==========
+
+.. toctree::
+   :maxdepth: 2
+
+   installation
+   how_weis_works
+
+
+Other Useful Docs
+=================
+
+.. toctree::
+   :maxdepth: 2
+
+   how_to_contribute_code
+   how_to_write_docs
+
+Indices and Tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/installation.rst

@@ -0,0 +1,36 @@
+WEIS Installation
+-----------------
+
+The recommended method for installing WEIS is with `Anaconda <https://www.anaconda.com>`_.
+This streamlines the installation of dependencies and creates self-contained environments suitable for testing and analysis.
+WEIS requires `Anaconda 64-bit <https://www.anaconda.com/distribution/>`_.
+
+Configure Anaconda Environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Setup and activate the Anaconda environment from a prompt (Anaconda3 Power Shell on Windows or Terminal.app on Mac)
+
+The installation instructions below use the environment name, "weis-env," but any name is acceptable.
+
+.. code-block:: bash
+
+    conda config --add channels conda-forge
+    conda create -y --name weis-env python=3.7
+    conda activate weis-env
+
+Note that older versions of anaconda on MacOS and Linux may instead require `source activate weis-env`
+
+.. _install:
+Install WEIS
+^^^^^^^^^^^^
+
+For all systems:
+
+.. code-block:: bash
+
+    git clone https://github.com/WEIS/WEIS.git
+    cd WEIS
+    python setup.py develop
+
+
+TODO : add to this as needed