Documentation maintenance

[toondm]

This issue lists all the review tasks of the documentation maintenance that we will do in the next few weeks (finish by 18/3). I propose to work in 2 stages, so that every file gets checked twice:

• First a review by the author of the code (or at least someone who is familiar with it) because he will know best which information is missing or wrong. Missing documentation should also be added at this stage, and documentation should be updated if necessary (e.g. because of the new data structure).
• Later a review by someone else

How to review and change docs

A branch docs-maintenance has been created, which will be merged with master once the maintenance is finished.

• Checkout branch docs-maintenance
• Preview docs locally, e.g. python run_mkdocs.py --preview mappers
• Make changes to .md file
• Push changes to remote (merge remote in local if necessary)

As everyone will be working on the files allotted to the, there will (should) be no merge conflicts.

Style & layout guide

• Use code style for:

  • class and method names (and plurals): Model, ModelParts, __init__, finalize
  • JSON keys and values: coupled_solver, delta_t

• Use code style + italics for:

  • files: run_simulation.py, parameters.json
  • folders: data_structure, /coupling_components/solver_wrappers/mapped.py

• Use normal text for:

  • referring to abstract principles (i.e. not a specific class): solver wrappers, mappers, coupled solver, data structure

• Title of markdown page (e.g. # Mappers, the first line of the MarkDown file):

  • should be brief and not repeat information that can be deducted from the structure of the documentation; e.g. for the Fluent solver wrapper: just use # Fluent and not # Fluent solver wrapper, as it is beneath Solver wrappers on the website
  • don't use class names (i.e. no camelcase), so not something like # SolverWrapperOpenFOAM

• For subtitles (that start with ##, ###,...), you can refer to class names or methods, but use code style in that case.

• If you refer to other MarkDown pages in the documentation, it can be useful to use a relative link. For more info, see docs documentation.

• Recommendation for links: it is nice that the link text gives you some information about where the link goes, so

  • good example: coconut documentation
  • bad example: this link

Stage 1: review by code-author (mostly) → 10/3

• [x] README.md: Henri
• [x] coupling_components.md: Henri
• [x] convergence_criteria.md: Axel
• [x] coupled_solvers.md: Nicolas
• [x] models.md: Nicolas
• [x] mappers.md: Toon
• [x] predictors.md: Nicolas
• [x] solver_wrappers.md: Henri
• [x] abaqus.md: Henri
• [x] fluent.md: Toon
• [x] kratos.md: Navaneeth
• [x] openfoam.md: Mathieu
• [x] python.md: Nicolas
• [x] data_structure.md: Navaneeth --> missing!
• [x] docs.md: Niels
• [x] tests.md: Axel --> extend to give good overview of different test options (single file, single method, explanation of -b, -v etc)

Stage 2: peer-review → 18/3

• [x] README.md: Toon
• [x] coupling_components.md: Axel
• [x] convergence_criteria.md: Nicolas
• [x] coupled_solvers.md: Henri
• [x] models.md: Henri
• [x] mappers.md: Mathieu
• [x] predictors.md: Axel
• [x] solver_wrappers.md: Toon
• [x] abaqus.md: Mathieu
• [x] fluent.md: Niels
• [x] kratos.md: Axel
• [x] openfoam.md: Navaneeth
• [x] python.md: Niels
• [x] data_structure.md: Mathieu
• [x] docs.md: Toon
• [x] tests.md: Navaneeth

[hdolfen]

I created a solver_wrappers.md file in the solver_wrappers directory with some general info about what a solver-wrapper does and an overview of the solvers for which a solver-wrapper is available and what versions are supported.

As this is a new .md-file, I need a volunteer to review it.

[nicolasdlss]

That's a nice idea, but the reason we have not done it so far, is that is less obvious as where to locate it in the website structure. What I did now, was create a tab General on the same level as Fluent, OpenFoam, ... It's not possible to link it with the higher level "Solver Wrappers".

[toondm]

What I did now, was create a tab General on the same level as Fluent, OpenFoam, ...

Good, that is nicely in line with the "General" tab under "Coupling Components".

[navaneethkn]

The issue is closed with the pull-request #101