Rhobincu la 18 mai 2026 13:50

2026-05-18T13:50:45Z

Rhobincu: Pagină nouă: = Week 10 Lab Activity: Documentation as Code with Doxygen = == Objective == Generate API documentation for your Oven Controller with Doxygen and publish it automatically to GitL...

2026-05-18T13:48:36Z

Pagină nouă: = Week 10 Lab Activity: Documentation as Code with Doxygen = == Objective == Generate API documentation for your Oven Controller with Doxygen and publish it automatically to GitL...

Pagină nouă

= 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 <code>doxygen -g</code>. Because Doxygen reads source directly, it needs no compiled binary and no CMake involvement --- the documentation job is completely independent of your build.

GitLab Pages serves a static website straight from a CI job. On this course's instance, <code>gitlab.cs.pub.ro</code>, the Pages wildcard domain is <code>pages.upb.ro</code>. With unique domains enabled (the default), your published site receives an unpredictable URL of the form <code>https://<project>-<6-char-id>.pages.upb.ro/</code>. 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 <code>pages:</code> property, and names the directory to publish using <code>publish:</code> 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.

# '''Generate the Doxyfile.''' Run <code>doxygen -g</code> in your project root. This creates a file named <code>Doxyfile</code> 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.

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

# '''Document the Oven Controller's public API.''' Add Doxygen comments to the main class and its public methods. Each public function should have a <code>\brief</code>, plus <code>\param</code> and <code>\return</code> 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.''

# '''Build and check locally.''' Run <code>doxygen Doxyfile</code>. Open <code>html/index.html</code> 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.

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

# '''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 <code>create-pages</code> 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:

# <code>Doxyfile</code> --- your configured Doxygen configuration file.
# <code>.gitlab-ci.yml</code> --- including the new <code>docs</code> stage and the <code>create-pages</code> 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 <code>EXTRACT_ALL = NO</code>, <code>WARN_IF_UNDOCUMENTED = YES</code>, and <code>WARN_AS_ERROR = YES</code> 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 <code>docs/architecture.md</code> describing how the Oven Controller's pieces fit together. Add it to the Doxyfile's <code>INPUT</code>. 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 <code>publish:</code> must exactly match where Doxygen actually wrote the HTML. With the default <code>HTML_OUTPUT = html</code> and an empty <code>OUTPUT_DIRECTORY</code>, that directory is <code>html</code>. If you changed either setting, update <code>publish:</code> 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 <code>doxygen</code> command itself locally (Task 4) so you are confident before merging.

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

* '''No diagrams in the output.''' <code>HAVE_DOT = YES</code> requires the Graphviz <code>dot</code> tool to be installed. Make sure your CI <code>before_script</code> installs <code>graphviz</code>, not only <code>doxygen</code>.

* '''Doxygen reports warnings about undocumented members.''' With <code>EXTRACT_ALL = YES</code> this is harmless --- the site still builds. It only fails the job if you also set <code>WARN_AS_ERROR = YES</code> (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 <code>create-pages</code> 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.

@@ Linia 7: / Linia 7: @@
 == 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 <code>doxygen -g</code>. Because Doxygen reads source directly, it needs no compiled binary and no CMake involvement --- the documentation job is completely independent of your build.
+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 <code>doxygen -g</code>. Because Doxygen reads source directly, it needs no compiled binary --- the documentation job does not depend on your <code>build</code> stage at all, and in this lab it runs <code>doxygen Doxyfile</code> directly without involving CMake. (You ''can'' add a <code>docs</code> target to <code>CMakeLists.txt</code> 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, <code>gitlab.cs.pub.ro</code>, the Pages wildcard domain is <code>pages.upb.ro</code>. With unique domains enabled (the default), your published site receives an unpredictable URL of the form <code>https://&lt;project&gt;-&lt;6-char-id&gt;.pages.upb.ro/</code>. You read the exact URL from '''Deploy &gt; Pages''' in the GitLab UI after the first successful deployment --- you cannot know it in advance.

SDPT Lab 10 - Revizia istoricului

Rhobincu la 18 mai 2026 13:50

Rhobincu: Pagină nouă: = Week 10 Lab Activity: Documentation as Code with Doxygen = == Objective == Generate API documentation for your Oven Controller with Doxygen and publish it automatically to GitL...