Feat/pages

[robert-burger]

No description provided.

[gemini-code-assist]

Summary of Changes

Hello @robert-burger, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request standardizes the documentation build process by renaming the primary output directory for generated documentation from doc to docs. This change is reflected across the Doxygen configuration and the associated Makefile, ensuring consistency and potentially aligning with common conventions for documentation hosting.

Highlights

• Documentation Output Path Renaming: The primary change in this PR is the renaming of the default documentation output directory from doc to docs. This affects where Doxygen generates various documentation formats (HTML, LaTeX, Qt Help Project files).
• Build System Configuration Update: The Makefile.doc has been updated to reflect the new docs directory for building and deploying documentation, including the path to the create_directory_listing.py script used for GitHub Pages.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request refactors the documentation output directory from doc to docs. The changes are consistent across the Makefile.doc and doxygen.cfg files. My review has identified a critical issue in the Makefile that will break the documentation deployment pipeline, as well as a high-severity issue in a referenced CSS file that will break the documentation's styling. I've also noted a medium-severity issue in a Python script that generates invalid HTML. I've provided detailed feedback on these points.

[gemini-code-assist]

While changing BUILDDIR to docs is consistent with the other changes, this change highlights a critical issue later in the gh-pages target. The commands on lines 29-30 use $(BUILDDIR) to copy CSS and HTML files:

29:	cp $(BUILDDIR)/*.css $(GH_PAGES_DIR_NAME)/
30:	cp $(BUILDDIR)/index.html $(GH_PAGES_DIR_NAME)/

However, the Doxygen output is generated into $(BUILDDIR)/html (based on doxygen.cfg), and this directory is moved to $(DOCS) on line 26. Consequently, the cp commands on lines 29-30 will fail because the source files do not exist in $(BUILDDIR). This will break the gh-pages deployment.

This appears to be a pre-existing issue, but since you are modifying BUILDDIR, it's a good opportunity to fix it. The fix might involve copying the files from $(BUILDDIR)/html before the mv command, or from $(DOCS) after it.

[gemini-code-assist]

The path to the stylesheet is updated correctly. However, I've noticed a potential issue within the referenced stylesheet docs/doxygen_theme_flat_design/src/doxygen-style.css. On line 5 of that file, it uses ::root to define CSS variables. The correct CSS pseudo-class is :root (with a single colon). Using the invalid ::root selector will prevent the CSS variables from being defined, which will likely break the custom theme's appearance.

[gemini-code-assist]

This line correctly calls the Python script to generate the directory listing. However, the script create_directory_listing.py appears to have a couple of issues:

1. It writes <!DOCTYPE html> at the beginning of content.html. If content.html is a fragment to be included in another page, it should not contain a DOCTYPE declaration.
2. The generated <a> tags have class="index.html", which is likely a mistake and should be a more descriptive class name (e.g., class="branch-link").

Since this line is being modified, it would be a good time to also fix the script it calls to ensure valid HTML is generated.