Documentation for Elastica

[skim0119]

@tp5uiuc @nmnaughton @armantekinalp @bhosale2

Context

Currently, documentation and tutorials for elastica can be found in three different places: website (cosseratrods.org), PyElastica API documentation (docs.cosseratrods.org), and PyElastica GitHub examples. Some contents are duplicated, outdated, and difficult to follow.
Since the new elastica++ package is coming soon, we should discuss how to organize these properly.

The goal is to reduce duplicated contents, so that the contents can be managed serially, and to provide easy-to-follow guidelines for first-time users. Here is some suggestion from the previous discussion with @tp5uiuc. Feel free to add your opinion.

CosseratRods Website

The fact that we have a dedicated website for Elastica project is useful.
The package is developed for research purposes, so a proper introduction to the research and scholarly effort would benefit everyone.

The website (already) includes:

• introduction to the project, background, and developer group
• Cosserat Rod theory and underlying papers
• Side/secondary projects (e.g. Elastcia+RL, etc)
• Link to the software (PyElastica, Elastica++)
• Related publications/Press
• How to contact us

Remove from the website:

• Pyelastica tutorial - This should go into pyelastica documentation.
  • PyElastica guide can be moved to pyelastica documentation page. Having API and user-guide in the same website is probably better for users to understand.
  • First-time users should be introduced to a more detailed guide. We shouldn't assume that people know the structure of the PyElastica.

PyElastica API Documentation

The documentation is located in PyElastica/docs, using spinx, and linked with ReadtheDocs to synchronize the webpage.

• User guideline
  • Teach basics of how to use PyElastica modules
• Example cases
  • Binder as run cases
• PyElastica API
• Link to Elastica++ docs

PyElastica Examples

Example codes should be placed in a separate repository,
We suggest people to install PyElastica using pip install, which means example codes are not exposed.
Maybe we can create PyElastica-Gallary repo to collect show-cases and refer them to the documentation webpage.
Each case can be properly introduced in PyElastica API so that people have access to the scripts and use them as templates.

I suggest we include basic cases as submodules so that users can test installation.

python -m pyelastica.examples.AxialStretchingCase
python -m pyelastica.examples.ButterflyCase
python -m pyelastica.examples.TimoshenkoCase

Elastica++ Examples

We can decide later whether the documentation for Elastica++ should be included in PyElastica documentation.
I feel like it is better to have a separate website.

• Link to PyElastica docs

[nmnaughton]

Moving the tutorial from the main webpage to the docs subdomain should be pretty easy, though we would need to reformat to the RTD theme from the website theme, however, both websites can handle markdown so it should not be too bad.