Move docs to Jupyter Book and expand content

[rafmudaf]

Feature or improvement description
This pull request converts the existing Jekyll-based documentation to use Jupyter Book. I've also migrated most of the information from the v2 documentation, and added a few new areas. It is still a work in progress, but I wanted to start getting feedback.

Since this is on my fork, a live preview can be seen here: https://www.rafmudaf.com/floris/intro.html. Alternatively, you can pull these code changes to your local computer and build it with Jupyter Book (pip install jupyter-book):

cd floris
jupyter-book build docs/

Related issue, if one exists
None, but the current documentation is minimal.

Impacted areas of the software
Online documentation

[rafmudaf]

I've added a structure for automatically generated API documentation. See it at https://www.rafmudaf.com/floris/api_docs.html. There's quite a bit of work to do yet:

• Improve the module docstrings for accuracy and relevant content
• Include type hints in the function signatures ('sphinx_autodoc_typehints')
• Include the api docs in the table of contents for the whole book to make navigation easier

[rafmudaf]

@paulf81 what do you think about describing the input file in this format: https://www.rafmudaf.com/floris/input_reference.html?
This uses a Sphinx-extension to parse comments in a yaml file and structure them in this format automatically.

I'm not entirely into it because it's a little hard to read when there's a lot of text. However, that could probably be fixed by somehow formatting the yaml fields in some form other than bold text such as a different color or font.

[paulf81]

I think it looks like nice and neat, I might also ping @kflemin if she has any tips on documentation generation she could share from her experience?

[RHammond2]

@rafmudaf this is a major improvement over the current docs site, and on the whole I like it a lot, so I've included a number of things that stuck out to me as areas of improvement as I was going through the site in decent detail.

FLORIS Intro

• Seems like this might be a good place to highlight the main FLORIS papers/tutorials (even if it's cross referencing from another section)
• Could be a nice place for some sleek imagery coming from FLORIS that's highlighting some of the capabilities (even the 2.x to 3.x performance comparisons)

Installation

• Break it into sections for pip, conda, and source with a short sentence or two describing each
• Additional/Optional dependencies section for pyoptparse, etc

Developer's Guide

• Might move that up to be just under the installation page
• The right sidebar isn't showing the subsections like Unit Testing
• The testing sections should just have the code one-liner for running that example as a code snippet
• It might be worthwhile to give a quick overview of the Git/GH workflow as a numbered list for a typical feature contribution workflow just to be exceedingly clear about what we want

Background and Concepts

Intro

• floris simulation and tools could go second after providing a little more high level details about interacting with FLORIS

Get turbine power

• Should we consider something like rich/tabulate to improve our standardized output printing in place of reimplementing the same workflows all the time. Essentially, a floris.tools.print module would be my proposal for this

Visualization

• If you put a ; after the plotting routines or add plt.show() as the last line then you'll be able to suppress those matplotlib outputs that show up just before the actual plots
• It seems like there should be subsections to this heading so that it's easier to follow
• Probably not the right place, but it seems like we should have the plot_rotor_values using the same color bar so it's easier to translate between wind speeds

API

• I find the layout a little bit awkward, which is probably more to do with the autosummary setup for automatically populating the pages, but it's not clear to me that the first thing a user sees should be the logging manager, which they don't directly interact with in any meaningful way.
• Building on that, I think that it'd more helpful if the API docs were broken down into the following topical areas (or something similar):
  • Base Classes, Mixins, and Configurations
    • logging, types, utilities, version, Base(?), BaseModel(?)
  • Simulation
    • Introduce the primary building blocks: turbine, farm, flow_field, and floris
    • Modeling components: grid, solver, and wake
    • Wake modeling: combination, deflection, turbulence, velocity
  • Tools

Code Quality

• I like this, but I feel like it could have a better home, maybe even at the end of the main page or with a changelog type page

[rafmudaf]

I'm merging this pull request now but the comments here will be addressed in an upcoming pull request.