SDPT Lab 10

Week 10 Lab Activity: Documentation as Code with Doxygen

Objective

Generate API documentation for your Oven Controller with Doxygen and publish it automatically to GitLab Pages. This lab is deliberately short --- once the documentation pipeline works, the rest of the session is yours for capstone work.

Background

Doxygen parses your source code and your specially-formatted comments and produces a cross-referenced HTML website. It is configured by a single file, the Doxyfile, generated with doxygen -g. Because Doxygen reads source directly, it needs no compiled binary --- the documentation job does not depend on your build stage at all, and in this lab it runs doxygen Doxyfile directly without involving CMake. (You can add a docs target to CMakeLists.txt that wraps the same command, as the lecture notes, but this lab does not require it.)

GitLab Pages serves a static website straight from a CI job. On this course's instance, gitlab.cs.pub.ro, the Pages wildcard domain is pages.upb.ro. With unique domains enabled (the default), your published site receives an unpredictable URL of the form https://<project>-<6-char-id>.pages.upb.ro/. You read the exact URL from Deploy > Pages in the GitLab UI after the first successful deployment --- you cannot know it in advance.

The modern GitLab Pages CI syntax marks a job as a Pages job using a pages: property, and names the directory to publish using publish: inside it. The job itself can have any name. See the Week 10 lecture slide "CI Integration: Publishing to GitLab Pages" for the shape of this job.

For Doxygen comment syntax, see the lecture's before/after Oven Controller slides. Reference material: the Doxygen manual at https://www.doxygen.nl/manual/, and the special-command list at https://www.doxygen.nl/manual/commands.html.

Tasks

Work on a feature branch opened from a tracked Issue. Open a Merge Request when you are ready to integrate.

1. Generate the Doxyfile. Run doxygen -g in your project root. This creates a file named Doxyfile containing every Doxygen setting with its default value and an explanatory comment. Commit it as-is in its own commit, so your later configuration changes are visible as a clean diff.

1. Configure the Doxyfile. Edit at least the following settings: PROJECT_NAME and PROJECT_NUMBER; INPUT (point it at your source and header directories and your README.md); RECURSIVE = YES; EXTRACT_ALL = YES; GENERATE_HTML = YES; GENERATE_LATEX = NO; HAVE_DOT = YES (enables the Graphviz class and call diagrams); and USE_MDFILE_AS_MAINPAGE (set to your README.md so it becomes the documentation landing page). Leave OUTPUT_DIRECTORY empty and HTML_OUTPUT at its default html, so the generated site lands in ./html.

1. Document the Oven Controller's public API. Add Doxygen comments to the main class and its public methods. Each public function should have a \brief, plus \param and \return where they apply. Write genuine contracts --- units, valid ranges, error behavior --- not restatements of the function name. The lecture's before/after example sets the standard. This task is verified through your published documentation site, not submitted as a file.

1. Build and check locally. Run doxygen Doxyfile. Open html/index.html in a browser and confirm that your classes, your comments, and (if Graphviz is installed locally) the diagrams all appear as expected. Fix anything that looks wrong before moving on.

1. Add the documentation job to CI. Edit .gitlab-ci.yml:
   1. Add a new docs stage as the last stage.
   2. Add a job (suggested name create-pages) in that stage. It should use a stock Debian or Ubuntu image, install doxygen and graphviz in a before_script, run doxygen Doxyfile in its script, and publish the html directory using the pages: property.
   3. Restrict the job to the default branch with a rules: entry, so the documentation deploys only from released code.

1. Publish and verify. Push your branch and open the Merge Request. Note that because the job is restricted to the default branch, it will not run on your feature-branch pipeline --- this is expected. Once the MR is merged, the pipeline on the default branch runs the create-pages job. Then open Deploy > Pages, find your site's live URL, open it, and confirm the documentation is served correctly. Paste that URL into your Merge Request description.

Deliverables

Submit exactly two files:

1. Doxyfile --- your configured Doxygen configuration file.
2. .gitlab-ci.yml --- including the new docs stage and the create-pages job.

In addition, your Merge Request description must contain the live GitLab Pages URL from Task 6. The quality of your Doxygen comments (Task 3) is assessed by visiting that URL.

Stretch tasks (optional)

Pick at most one. Neither earns extra points; both make your capstone documentation noticeably better.

• Turn documentation into a real gate. Set EXTRACT_ALL = NO, WARN_IF_UNDOCUMENTED = YES, and WARN_AS_ERROR = YES in your Doxyfile. Now Doxygen exits with an error --- failing the pipeline --- whenever a public entity has no documentation. Then document everything until the job passes. This is how documentation becomes a true quality gate rather than a suggestion.

• Add a hand-written architecture page. Create docs/architecture.md describing how the Oven Controller's pieces fit together. Add it to the Doxyfile's INPUT. It will appear as a first-class page in your documentation site, alongside the auto-extracted API reference.

Common pitfalls

• The published site is 404 or shows the wrong content. The directory named in publish: must exactly match where Doxygen actually wrote the HTML. With the default HTML_OUTPUT = html and an empty OUTPUT_DIRECTORY, that directory is html. If you changed either setting, update publish: to match.

• The docs job never runs. If you restricted it to the default branch, it will not appear on feature-branch or Merge Request pipelines --- only after the merge. This is correct behavior. Verify the doxygen command itself locally (Task 4) so you are confident before merging.

• The pages: keyword causes a YAML or pipeline error. The Pages CI syntax has changed across GitLab versions. The pages: property with publish: inside it is the current form. If your instance rejects it, check the GitLab version of gitlab.cs.pub.ro and consult its documentation for the exact accepted syntax.

• No diagrams in the output. HAVE_DOT = YES requires the Graphviz dot tool to be installed. Make sure your CI before_script installs graphviz, not only doxygen.

• Doxygen reports warnings about undocumented members. With EXTRACT_ALL = YES this is harmless --- the site still builds. It only fails the job if you also set WARN_AS_ERROR = YES (see the stretch task).

• I cannot find my Pages URL. It is under Deploy > Pages in the GitLab project sidebar, and only appears after the create-pages job has succeeded at least once on the default branch.

Looking ahead

Next week is the last: Capstone Synthesis. Your CI pipeline is now complete --- build, test, lint, sanitize, and docs. We step back, look at the whole system you have built, cover a few industry topics, and reserve lab time for capstone polish and a dry run of your project presentation.