Question on order of files listed by doxygen output
jafingerhut opened this issue · comments
@AdarshRawat1 This is primarily for you to think about.
Right now, the order that *.md files appear in the auto-generated doxygen output here: https://p4lang.github.io/p4c/index.html
appears to be sorted by the full path name. So, for example, the *.md files within the backends/ubpf directory and subdirectories occur in this order:
backends/ubpf/docs/EXAMPLES.md
backends/ubpf/README.md
backends/ubpf/tests/README.md
Is there a doxygen option to make files in shallower directories always appear before those in directories beneath them? i.e. in the following order for the 3 files above?
backends/ubpf/README.md
backends/ubpf/docs/EXAMPLES.md
backends/ubpf/tests/README.md
I think that would be a more logical ordering to generate in the output.
There is no specific feature for this, but there are few workarounds for this.
Suggested
Pass the names of files to the doxygen in the sequence in which we want them to be rendered, this should provide easier modifications to sequence without modifying any other file. This method is also used by doxygen's documentation .
Extra Context
-
Rename the files to modify the sequenece i.e. prefix file names with 1,2,3 or A,B,C
-
Using
/pageand/subpagecommands within the Markdown files. ( But these commands are visible in GitHub README preview. ) .
The list of *.md files changes pretty slowly, so I suspect the explicit list of files might be a reasonable approach. The main issue is remembering to add something to it when a new *.md file is added, but no big deal if there is a time lag there.
Actually, if we have an explicit sequence of file names that gives the order to use, we should also be able to run some code that prints a warning/error message if there are other *.md files that are not in that sequence, as a noisy way to notice that it needs to be updated.
If we give doxygen an explicit sequence of files for the order to show them in the doxygen-generated HTML page, it might also be good to omit some pages that currently do not have enough useful content to be worth including, until perhaps later if someone fleshes them out more:
backends/p4tools/cmake/README.md
backends/p4tools/cmake/README.md
backends/p4tools/common/lib/README.md
backends/p4tools/common/README.md
backends/p4tools/modules/testgen/lib/README.md
Below is a suggested order for showing the remaining ones:
docs/README.md
docs/doxygen/00_revision_history.md
docs/doxygen/01_overview.md
docs/IR.md
lib/README.md todo? Change top level heading to "# Common P4C utility functions"
ir/README.md
CHANGELOG.md
backends/bmv2/README.md
backends/dpdk/README.md
backends/ebpf/README.md
backends/ebpf/psa/README.md
backends/graphs/README.md
backends/p4fmt/README.md
backends/p4test/README.md
backends/p4tools/README.md
backends/p4tools/CONTRIBUTORS.md
backends/p4tools/modules/smith/README.md
backends/p4tools/modules/testgen/README.md
backends/p4tools/modules/testgen/benchmarks/README.md
backends/p4tools/modules/testgen/targets/bmv2/test/README.md
backends/tc/README.md
backends/ubpf/README.md
backends/ubpf/docs/EXAMPLES.md
backends/ubpf/tests/README.md
Actually, if we have an explicit sequence of file names that gives the order to use, we should also be able to run some code that prints a warning/error message if there are other
*.mdfiles that are not in that sequence, as a noisy way to notice that it needs to be updated.
This would be great to have, but as you mentioned in you mentioned -
it might also be good to omit some pages that currently do not have enough useful content to be worth including, until perhaps later if someone fleshes them out more:
So, we will have 2 files, one for keeping track of sequence of output files and other for keeping list of files to be ignored. Then we can track files that are new and do not fall in both categories / files.
Below is a suggested order for showing the remaining ones:
Thank you, @jafingerhut , for the curated list!!
Fixed with this PR: #4758