Move most all documentation to https://simvascular.github.io

[ktbolt]

Use Case

It would be good to have a single location for svFSIplus documentation.

Problem

There are currently two sources of svFSIplus documentation.

1) The primary documentation for all applications is in https://github.com/SimVascular/simvascular.github.io. I am currently replacing svFSI documentation with svFSIplus documentation.

2) The other source of documentation is in https://github.com/SimVascular/svFSIplus/tree/main/Documentation/pages. This duplicates a lot of information in 1.

Solution

I am going to remove https://github.com/SimVascular/svFSIplus/tree/main/Documentation/pages and the gh-pages branch.

I will keep the building and testing documentation on https://github.com/ktbolt/svFSIplus as README.md files.

I will add a Developers Guide section to https://simvascular.github.io/#documentation.

Alternatives considered

None

Additional context

No response

Code of Conduct

• [X] I agree to follow this project's Code of Conduct and Contributing Guidelines

[mrp089]

I agree we should have a single location for the svFSIplus documentation, but I favor having everything in this repository.

There are two options to where to store documentation:

1. Documentation for SimVascular, svSolver, svFSI, svOneDSolver, svZeroDSolver in one repository
2. Documentation for each solver in its respective repository

We currently have a mix of both: store the documentation with the source code and link it from a central website, which has advantages:

• Storing source and documentation together makes it easy to update, see, e.g., 0D interface, Docker, or Testing. In contrast, the respective folder in simvascular.github.io has never been updated
• Other (big) open-source projects do this as well, e.g., deal.ii and PETSc
• Documentation for five different tools in one repository is too much

There are some improvements we could make:

• Move the remaining documentation in simvascular.github.io to this repository
• Integrate the documentation better with simvascular.github.io
• Create an examples page that combines and links the readmes of our test cases

@ktbolt, I'm happy to hear arguments about why option 1 would be better. I'm also curious to hear opinions from developers @aabrown100-git, @kharold23, @zasexton, @dcodoni, @menon-karthik, @MatteoSalvador.

[aabrown100-git]

I don't feel too strongly, but I tend to agree with Martin. It feels more natural to have the documentation with the code. If someone adds a feature, they can update the documentation in the same pull request, rather than a separate pull request in another repository.

[MatteoSalvador]

I also tend to agree with @mrp089 and @aabrown100-git. In this way, features specific to SimVascular, svSolver, svFSI, svOneDSolver and svZeroDSolver can be documented separately. These repositories are large and quite different in terms of the functionality they provide. Furthermore, the documentation can be controlled independently by each research subgroup, and grows better in a distributed way.

[MatteoSalvador]

After talking to @alisonmarsden, I think the best solution would be to have two levels of documentation:

1. For developers/internal users: this can be differentiated for each repository (SimVascular, svSolver, svFSIplus, svOneDSolver, svZeroDSolver, ...). In this way, we can specify technical details about routines, functionalities, numerical schemes, mathematical models, etc. independently for each repository, also inside the source code.
2. For external users: this can be done here, for all applications, and should provide an interface and generic instructions/guidelines that apply to all repositories.

[dcodoni]

I agree with this last solution @MatteoSalvador proposed. I prefer to have a documentation specific to a repository in the repository itself. I find it easier to update too, avoiding possible confusion.

[menon-karthik]

I discussed with @ktbolt yesterday and we agreed on the same solution as @MatteoSalvador mentioned above. We can have code-specific details with each repository. But for end-users who just want to use Simvascular, it might make sense to provide an overview on how to use each solver, format input files, etc. on the Simvascular website since that's supposed to serve as an entry-point for users and it's where the tutorials are (at least for svSolver).

One concern I have is that anyone who wants to dig slightly beyond just being a user will need to look at documentation in two different places - the user docs on the SV website and the code docs in the repository. Do we have a good solution to that?

[dcodoni]

@menon-karthik I do not know if this is relevant, but few times I saw documentation of big project that just point to the git repository through an hyperlink for more details on some parts. Maybe it can be done the same for SV website.

[ktbolt]

Thank you @mrp089 @mrp089 @MatteoSalvador @menon-karthik for your input.

The two levels of documentation approach makes the most sense so we will go with that.

Most of our effort needs to be focused on user documentation. This should include

• theory section
• file formats
• running the solver
• solver output
• common problems
• use case examples
• any implementation details that a user may find useful

The developer documentation should be organized well and have sections including

• architecture (if there is one!)
• organization
• important implementation details
• how to modify the code
• doxygen api docs
• building and deployment and testing

I've added a Developer Guide section to the SimVascular Website which has most of these.

We need to reorganize and clean up https://simvascular.github.io/svFSIplus including

• the main page has svFSI rather than svFSIplus
• references a bunch of Fortran svFSI things
• table of contents menu on the wrong side

to make it useful and nice to look at.

Doxygen is only useful if the code is commented and commented well, we need to work on that.

[ktbolt]

I am going to start cleaning up and reorganizing the gh-pages documentation.

[ktbolt]

I've cleaned up the gh-pages documentation, left the doxygen docs there and moved the other documentation (e.g. build instructions) to the README file

[ktbolt]

Selecting the svFSIplus Internal Code Documentation link in the README brings up the doxygen documentation

[ktbolt]

Up and running!