nasa / nasa/cFS

Revise and improve mission documentation build

Open
#877 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug docs
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:

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:

  1. cFE User Guide
  2. OSAL API Guide
  3. 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

  1. Documentation Builds pass
  2. 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:

Reporter Info
Keegan Moore / NASA GSFC

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.