New expanded feature docs

[bbrelje]

Purpose

The feature docs are nonexistent for pygeo. We need feature documents that explain the most common use cases and provide some intutition for how the geometry works, especially FFD

Type of change

What types of change is it?

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (non-backwards-compatible fix or feature)
• Code style update (formatting, renaming)
• Refactoring (no functional changes, no API changes)
• Documentation update
• Maintenance update
• Other (please describe)

Testing

Docs build correctly

Checklist

Put an x in the boxes that apply.

• I have run flake8 and black to make sure the code adheres to PEP-8 and is consistently formatted
• I have run unit and regression tests which pass locally with my changes
• I have added new tests that prove my fix is effective or that my feature works
• I have added necessary documentation

[anilyil]

We should probably add the DVGeoVSP and ESP classes to the auto-generated docs. I am guessing you are on this, if not, let me know and I can add the pages to the documentation.

[marcomangano]

Actually:

Extension error:
Could not import extension embed_code (exception: No module named 'openmdao')

[eirikurj]

@bbrelje do we need the openmdao embed_code extension (and the associated code)? Can we not achieve the same with the built-in sphinx literalinclude extensions like we do for our other tutorials e.g.,

.. literalinclude:: ../tutorial/aero/geometry/generate_wing.py
    :start-after: # rst Imports
    :end-before: # rst Airfoil file

[bbrelje]

@bbrelje do we need the openmdao embed_code extension (and the associated code)? Can we not achieve the same with the built-in sphinx literalinclude extensions like we do for our other tutorials e.g.,

.. literalinclude:: ../tutorial/aero/geometry/generate_wing.py
    :start-after: # rst Imports
    :end-before: # rst Airfoil file

wait what is this? I've never seen this before

[bbrelje]

@anilyil good catch, I can replicate everything with the literalinclude directive so I can remove the openmdao dependency

[ewu63]

@bbrelje do we need the openmdao embed_code extension (and the associated code)? Can we not achieve the same with the built-in sphinx literalinclude extensions like we do for our other tutorials e.g.,

.. literalinclude:: ../tutorial/aero/geometry/generate_wing.py
    :start-after: # rst Imports
    :end-before: # rst Airfoil file

I think @bbrelje wants the code to be executed and the output shown on screen, like what we have for some OpenMDAO-based repos. This avoids having to update the outputs as the code behaviour changes.

[eirikurj]

@nwu63 right thats what I though too initially, and maybe that is the ultimate goal here. But it seems that only the code option is used here, which suggest that its only "cropping" and including a specific block of code and thats why I suggested the literalinclude.

[ewu63]

@nwu63 right thats what I though too initially, and maybe that is the ultimate goal here. But it seems that only the code option is used here, which suggest that its only "cropping" and including a specific block of code and thats why I suggested the literalinclude.

I see, yeah that makes sense. There are some difficulties in using embed_code, the main obstacle being that you need the code to be installed and executed on the RTD server, which may be difficult to do especially if it has complex dependencies. The easiest approach would definitely be using literalinclude.

[ewu63]

FYI #72 has been merged @bbrelje

[marcomangano]

Some minor edits, but I am now pretty confused by the "additional" embedded points included in the cylinder example. What's the idea behind that?

[marcomangano]

I would rephrase a bit like this, but feel free to further edit:
"There are two primary approaches to geometry parameterization: generative and deformative.
In pyGeo, we primarily use a free form deformation (FFD) approach, which belongs to the latter category.
This approach does not require the parameterization of the baseline geometry (as is the case for a generative approach such as CAD) because we only parameterized the changes with respect to the unperturbed geometry"

[hajdik]

Re: the additional embedded points: Josh requested showing the FFD embedding volume that can be shown using #133

[marcomangano]

Mmm.. I think I am misunderstanding what these blue points represent. Are they the "embedded volume" that's returned after #133? to me they look like an extra "random" pointset and the shaded area is already effective at showing the extent of the FFD volume. We should clarify where they is coming from because we previously refer to the blue triangles that define the cylinder as pointset, and they are the "deformation target".
Hope I am not making things more confusing, we can talk offline

[joanibal]

LGTM, merge it!

[marcomangano]

Good job everyone!