Revise and improve mission documentation build
Nobody has claimed this yet.
- Dominant language
- C
- Stars
- 1.5k
- Forks
- 391
- Avg merge
- 1d 11h
- Merged PRs (30d)
- 19
Description
Checklist (Please check before submitting)
- I reviewed the Contributing Guide.
- I performed a cursory search to see if the bug report is relevant, not redundant, nor in conflict with other tickets.
Describe the bug
In the following issues / PRs, we identified a failing mission-doc build:
- https://github.com/nasa/cFS/issues/875
- https://github.com/nasa/cFS/pull/876
- https://github.com/nasa/cFE/issues/2676
- https://github.com/nasa/cFE/pull/2677
The error seemed to be caused because the output mission doc PDF was far too large.
In those PRs, we disabled that workflow (to prevent the noise in the pipeline).
This issue is a follow-on to work the larger effort to fix the mission documentation.
We were generating the following:
- cFE User Guide
- OSAL API Guide
- Combined Mission Documentation
The third seemed to be a combo of the first two, plus additional documentation from each app in the build.
Instead, perhaps we should update the pipeline to generate a PDF for each of the modules separately, rather than combining them together. That way, each of the resulting files is more likely to stay under the size limits of pandoc/latex.
To Reproduce
- Rerun the workflows from the v7.0.0 draco tags, or one of PRs that started experiencing these errors (listed below in additional context)
Expected behavior
- Documentation Builds pass
- Documents are manageable (not too large, well-scoped, no duplicates)
Code snips
N/A
System observed on:
- Ubuntu / GitHub Runner containers
Additional context
The failing mission doc builds started with the v7.0.0 draco updates:
- https://github.com/nasa/cFS/pull/871
- https://github.com/nasa/cFS/pull/872
- https://github.com/nasa/cFS/pull/873
Reporter Info
Keegan Moore / NASA GSFC
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by rerunning the documentation workflows from the v7.0.0 draco tags or the referenced PRs 871–873, and review issues 875 and 2676 plus PRs 876 and 2677. Done means the documentation builds pass and produce manageable, well-scoped PDFs without duplicate content, while separating module documents as appropriate.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, latex
- Domain
- build-system, ci-cd, documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100