Create a short ForTrilinos User's Guide

trilinos / ForTrilinos

ForTrilinos provides portable object-oriented Fortran interfaces to Trilinos C++ packages.

https://trilinos.github.io/ForTrilinos

BSD 3-Clause "New" or "Revised" License

24 stars 12 forks source link

Create a short ForTrilinos User's Guide #159

Open aprokop opened 6 years ago

aprokop commented 6 years ago

The content could be:

Installation
- Take installation instructions from existing RTD
- Talk about spack option (btw, this will have to be updated)
Brief overview and the general gist
- Try to steer users to the existing Trilinos documentation
- Highlight the differences (like native Fortran arrays, and few functions with different semantics)
Provide few examples
- Could use existing power method example
Talk a bit about performance

aprokop commented 6 years ago

The same text can be used in the guide and ReadTheDocs. The guide would simply server as something static and citable.

tjfulle commented 6 years ago

Do we need both the RTD and a guide? Can we just run the RTD through a latex generator and create a PDF?

aprokop commented 6 years ago

Yep, could probably do that. RTD already generates the pdf. The main differences would be: a) The report would be in report style (like Sandia report, or ORNL report) b) We would like to maybe start with something published (so that it could go to OSTI), and then maintain a live version through RTD.

tjfulle commented 6 years ago

Sounds good to me. That is what I am doing with the Tpetra documentation. It takes about 25 minutes to hand massage the sphinx generated LaTeX to play nice with the SANDReport classes, but it beats maintaining two versions.

aprokop commented 6 years ago

Is this something a python script could fix?

tjfulle commented 6 years ago

I'm the type that views every problem as a nail and python as Thor's magic hammer to smash it, but I haven't found a good way to consistently make the changes required using python. They're pretty pervasive - changing the class, modifying some of the colors that clash with SANDReport, fixing equations and tables, etc.

aprokop commented 6 years ago

Would still like this to be done, but may need to postpone for now.

kruger commented 4 years ago

I don't know the requirements on sphinx extensions (adventurous? limited?) but what about this extension: https://sphinx-fortran.readthedocs.io/en/latest/

Combined with the new tests?

Perhaps even more far-fetched would be to use this sphinx extension: https://sphinxcontrib-osexample.readthedocs.io/en/latest/

to allow the native trilinos documentation to show C++ (default), fortran, and python. That would be slick.