Docs[BMQ]: Use .dox files rather than .md files
#444
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Package group documentation in `libbmq` was converted to Markdown files named `README.md`, and which was tied to the directory containing the code for the package group using Doxygen `@dir` commands. However, when generating the documentation, this left several empty pages in the documentation named `README`, which we were not able to remove. The solution for this that this patch uses is to switch from `.md` files to `.dox` files, which contain a single Doxygen-style C++ comment containing the `@dir` command. Unlike `.md` files, these do not automatically create pages, so there is no empty `README` page created for each package group. The cost of this is that `.dox` files cannot be simple Markdown files, but instead need to be wrapped in a C++ comment. Signed-off-by: Patrick M. Niedzielski <[email protected]>
pniedzielski
added
bug
pniedzielski
added a commit
to pniedzielski/blazingmq
that referenced
this pull request
Nov 7, 2024
This patch introduces three new targets to the build system when Doxygen
is present:
- `apidocs`: Build the public API documentation for public libbmq
components. This target functions similarly to how the current
`Doxyfile` builds documentation.
- `internaldocs`: Build the internal documentation for all libbmq and
libmqb components. The documentation built by this target is
currently incomplete, and needs work along the lines of PRs bloomberg#443 and
bloomberg#444.
- `docs`: Build both the above documentation targets. This is a
dependency of `make all`, so it will run by default.
Signed-off-by: Patrick M. Niedzielski <[email protected]>
pniedzielski
added a commit
to pniedzielski/blazingmq
that referenced
this pull request
Nov 7, 2024
This patch introduces three new targets to the build system when Doxygen
is present:
- `apidocs`: Build the public API documentation for public libbmq
components. This target functions similarly to how the current
`Doxyfile` builds documentation.
- `internaldocs`: Build the internal documentation for all libbmq and
libmqb components. The documentation built by this target is
currently incomplete, and needs work along the lines of PRs bloomberg#443 and
bloomberg#444.
- `docs`: Build both the above documentation targets. This is a
dependency of `make all`, so it will run by default.
Signed-off-by: Patrick M. Niedzielski <[email protected]>
pniedzielski
added a commit
to pniedzielski/blazingmq
that referenced
this pull request
Nov 7, 2024
This patch introduces three new targets to the build system when Doxygen
is present:
- `apidocs`: Build the public API documentation for public libbmq
components. This target functions similarly to how the current
`Doxyfile` builds documentation.
- `internaldocs`: Build the internal documentation for all libbmq and
libmqb components. The documentation built by this target is
currently incomplete, and needs work along the lines of PRs bloomberg#443 and
bloomberg#444.
- `docs`: Build both the above documentation targets. This is a
dependency of `make all`, so it will run by default.
Signed-off-by: Patrick M. Niedzielski <[email protected]>
pniedzielski
added a commit
that referenced
this pull request
Nov 8, 2024
This patch introduces three new targets to the build system when Doxygen
is present:
- `apidocs`: Build the public API documentation for public libbmq
components. This target functions similarly to how the current
`Doxyfile` builds documentation.
- `internaldocs`: Build the internal documentation for all libbmq and
libmqb components. The documentation built by this target is
currently incomplete, and needs work along the lines of PRs #443 and
#444.
- `docs`: Build both the above documentation targets. This is a
dependency of `make all`, so it will run by default.
Signed-off-by: Patrick M. Niedzielski <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
*Issue number of the reported bug or feature request: #118 *
Package group documentation in
libbmqwas converted to Markdown files namedREADME.md, and which was tied to the directory containing the code for the package group using Doxygen@dircommands. However, when generating the documentation, this left several empty pages in the documentation namedREADME, which we were not able to remove.The solution for this that this patch uses is to switch from
.mdfiles to.doxfiles, which contain a single Doxygen-style C++ comment containing the@dircommand. Unlike.mdfiles, these do not automatically create pages, so there is no emptyREADMEpage created for each package group. The cost of this is that.doxfiles cannot be simple Markdown files, but instead need to be wrapped in a C++ comment.Testing
To verify these changes, run
doxygenin the root directory of the project and ensure that(1) there are no empty
READMEpages generated, and (2) the package groups are still properly documented.