- removed comment
Cactus documentation target AllDoc does not make all the documentation
Issue #642
closed
The Cactus
make AllDoc
command does not make all the documentation - specifically it does not make the ThornGuide consisting of documentation for all the thorns. It does make the individual thorn documents. Is there a reason for this? Perhaps in the past this was a performance issue, but the documentation can be generated in minutes now, and typically this is not done very frequently. I think we should change the system so that AllDoc generates all the documentation.
Keyword:
Comments (15)
-
-
- removed comment
Eriks points are good points, but that should not prevent us from building ThornGuide in AllDocs. We might want to build it last for that reason though, with an explicit dependency on everything else being built first - for the time being. I would welcome a patch which would do that. The other issues should be taken care of as well, eventually, and tickets for that would be welcome too. Those fixes however (all of them) should not be included in the next release. Ian: can you please document in the release notes that AllDoc does not (yet) build the complete ThornGuide, and that this will change in the future?
Concerning thorns with dysfunctional documentation: we should be able to catch those cases by not including thorns where the standalone thorn documentation already does not build.
-
- removed comment
We should not be making promises for future releases. We may want to decide otherwise.
Personally, I don't find a single, large thorn guide useful, because of several reasons -- it is too large, the chapter/section numbers are different for everybody (!) leading to communication problems, if you make a copy of a thorn to a different name/different arrangement, there are latex problems that are difficult to diagnose (duplicate symbols), etc. I would not mind if the single ThornGuide went away.
Also, ignoring thorns where the documentation doesn't build isn't always ideal either.
-
- removed comment
The underlying question is whether we treat a failure to build documentation as something that we just tolerate and ignore, or as something that needs to be corrected. If we want to correct it, we need to test it, e.g. by updating the nightly tests, and by recording failures in the release process.
Another question is whether it even makes sense to build a global ThornGuide. This will include all thorns present in the source tree, which is something that nothing else in Cactus does -- for example, there is no target to build a configuration consisting of all thorns. For example, copying a thorn will lead to latex errors unless one is careful with labels and references (and renames them). The resulting ThornGuide is also not portable, because section numbers etc. depend on what is present in the source tree. In addition, having one huge pdf file is rarely useful.
I suggest to remove the (global) ThornGuide as makefile target, and leave only the configuration-specific ThornGuides.
-
- removed comment
I agree that an overall -doc target is hardly necessary and could be easily replaced by a configuration-wide target. I also agree that this should be tested regularly. Heck, we could even let simfactory build it by default. We also build the utilities, which at least I almost never use.
One large file however has an advantage: it can easily be searched by any decent pdf viewer (which is how I use the Cactus documentation).
-
- removed comment
(I use a multi-document search facility provided by a certain company in California.)
- Should we add *-ThornGuide to Simfactory? (I say yes.) - Should we remove the global ThornGuide make option? (I also say yes.)
-
reporter
- removed comment
The global thorn guide does not make any sense, and should be removed, assuming that there is a way to get the configuration-specific thorn guides containing the same information (is this the case?).
- -ThornGuide suggests some sort of Cactus make-like syntax. I propose that SimFactory gets some new options which control documentation building. We could have "--doc" option to "sim build", and design some sub options for controlling which parts of the documentation to build. I agree that this should be done as part of the automated build and test. There should also be a (possibly the same) way to get this automatically generated documentation uploaded automatically to a publicly visible location.
-
- changed status to open
- removed comment
-
- changed milestone to ET_2012_05
- removed comment
-
reporter
- removed comment
Referring to
User: eschnett Date: 2012/05/07 02:15 PM
Modified: /trunk/lib/ sim-build.py
Log: Build documentation by default
If the documentation fails to build, this will be counted as a build failure of the configuration, and the automatic tests will not be run. Since we would like the tests to run even if the docs fail to build, I would like to be able to build the code and docs separately, and do this in the test script.
-
- removed comment
I would also like this to be separate. It doesn't really make sense to build all of the documentation when compiling Cactus on a cluster, does it?
-
- removed comment
I removed building the documentation from Simfactory again. Currently, please use
./bin sim execute gmake sim-ThornGuide to build the documentation.
My patch to Cactus above is still up for review.
-
- removed comment
Replying to [comment:12 eschnett]:
My patch to Cactus above is still up for review.
I haven't tested the patch, but am fairly familiar with that section of the Makefile. The patch looks good to me.
The only issue is that there doesn't seem to be a HTML version of the configuration specific ThornGuide make target, so we should add this as a target at the same time as removing the patch. I'd imagine this would just be a matter of copy-and-paste from the existing ThornGuideHTML target.
-
- changed status to resolved
- removed comment
Applied.
-
- edited description
- changed status to closed
- Log in to comment
- Assignee
- –
- Type
- Priority
- Status
- closed
- Component
- Cactus
- Milestone
- ET_2012_05
- Version
- –
- Votes
- 0
- Watchers
- 0
There are always thorns where the documentation does not build, which breaks ThornGuide. Also, if there are many arrangements or thorns, the latex mechanism which numbers them alphabetically (!) breaks. (In Cactus, chapters are numbered alphabetically -- I don't know whether this is still the case.) Looking at the individual arrangement's and thorn's documentation is most of the time sufficient because it contains the same information.