#1556: Online Thorn Guide broken -----------------------------------------+---------------------------------- Reporter: joachim.frieben@… | Owner: Type: defect | Status: confirmed Priority: major | Milestone: Component: EinsteinToolkit website | Version: Resolution: | Keywords: broken index -----------------------------------------+----------------------------------
Comment (by eschnett):
We just do not use section numbers. Think Unix directory -- the files are not numbered, they just have names. In our documentation, the sections should similarly be labelled by arrangement and thorn; adding integer numbers is not necessary.
Documentation is slightly different from source code. When building a configuration, we explicitly choose which thorns to include (thorn list), and ignore all others. These other thorns thus may contain code that doesn't compile, and this is fine.
With documentation, we want to have as much documentation available as possible. Requiring a thorn list to build documentation is a bad idea, because it prevents people from building documentation for many thorns that are just fine. Also, while thorns' source code often depend on each other (inheritance etc.), this is not the case for documentation; thorn documentation can be built independently for each thorn. - Preventing all documentation from being built because a user has a single (maybe even unused) thorn with a latex error doesn't make sense. This is different from an executable. - Building documentation only for a specific set of thorns is too limiting; this prevents people e.g. from looking at thorn PETSc until they add it to their thorn list. This is not necessary.