Skip to content

Commit f072b67

Browse files
Ozaqclaude
Ozaq
and
claude
committed
Flatten doc structure and modernise build
Flatten the three-category CLI tool hierarchy (DebugTools/, GeneralPurposeTools/, SpecialPurposeTools/) into a single cli_tools/ directory so users can scan all tools in one place. Consolidate the C and C++ API pages into one breathe-backed api.rst so the reference stays in sync with headers automatically. Rewrite CMakeLists.txt with native CMake targets (configure_file + add_custom_command) and CONFIGURE_DEPENDS globs so Ninja detects RST changes. Rename Doxyfile to Doxyfile.in with @variable@ placeholders. Improve build_docs.sh to substitute Doxyfile.in placeholders with sed, fix macOS portability (replace readlink -f), and correct the INPUT path. Add fdb wrapper section and tool summary tables to CLI index. Fix numerous typos and broken cross-references throughout. Co-Authored-By: Claude Opus 4.6 <[email protected]>
1 parent 0a58fa1 commit f072b67

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+466
-588
lines changed

‎docs/CMakeLists.txt‎

Lines changed: 48 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,58 @@
11
find_package(Doxygen 1.9 REQUIRED)
22
find_package(Sphinx REQUIRED)
33

4-
file(GLOB_RECURSE FDB_PUBLIC_HEADERS ${CMAKE_CURRENT_SOURCE_DIR}/../src/fdb5/api/*.h)
5-
file(GLOB_RECURSE PYFDB_SRCS ${CMAKE_CURRENT_SOURCE_DIR}/../src/pyfdb/*.py)
6-
file(GLOB_RECURSE Z3FDB_SRCS ${CMAKE_CURRENT_SOURCE_DIR}/../src/z3fdb/*.py)
7-
file(GLOB_RECURSE SPHINX_INPUT_FILES ${CMAKE_CURRENT_SOURCE_DIR}/*.rst)
8-
set(DOXYGEN_INDEX_FILE ${CMAKE_CURRENT_BINARY_DIR}/doxygen/html/index.html)
9-
set(SPHINX_INDEX_FILE ${CMAKE_CURRENT_BINARY_DIR}/sphinx/index.html)
10-
set(DOXYFILE ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile)
4+
# --- Paths ---
5+
set(FDB_API_HEADER_DIR "${PROJECT_SOURCE_DIR}/src/fdb5/api")
6+
set(DOXYGEN_OUTPUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/doxygen")
7+
set(SPHINX_OUTPUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/sphinx")
8+
set(DOXYGEN_XML_DIR "${DOXYGEN_OUTPUT_DIR}/xml")
9+
set(DOXYGEN_INPUT_DIR "${FDB_API_HEADER_DIR}")
10+
set(FDB_VERSION "${PROJECT_VERSION}")
1111

12-
file(GLOB_RECURSE PYFDB_DOC_TEST_SRCS ${CMAKE_CURRENT_SOURCE_DIR}/../docs/pyfdb/example.rst)
12+
# --- Input file globs ---
13+
file(GLOB_RECURSE FDB_PUBLIC_HEADERS CONFIGURE_DEPENDS "${FDB_API_HEADER_DIR}/*.h")
14+
file(GLOB_RECURSE PYFDB_SRCS CONFIGURE_DEPENDS "${PROJECT_SOURCE_DIR}/src/pyfdb/*.py")
15+
file(GLOB_RECURSE Z3FDB_SRCS CONFIGURE_DEPENDS "${PROJECT_SOURCE_DIR}/src/z3fdb/*.py")
16+
file(GLOB_RECURSE SPHINX_INPUT_FILES CONFIGURE_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/*.rst")
17+
list(FILTER SPHINX_INPUT_FILES EXCLUDE REGEX "_build")
1318

19+
# --- Output stamps ---
20+
set(DOXYGEN_INDEX_FILE "${DOXYGEN_OUTPUT_DIR}/html/index.html")
21+
set(SPHINX_INDEX_FILE "${SPHINX_OUTPUT_DIR}/index.html")
22+
23+
# --- Configure Doxyfile ---
24+
configure_file(
25+
"${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in"
26+
"${CMAKE_CURRENT_BINARY_DIR}/Doxyfile"
27+
@ONLY
28+
)
29+
30+
# --- Doxygen ---
31+
add_custom_command(
32+
OUTPUT ${DOXYGEN_INDEX_FILE}
33+
COMMAND ${CMAKE_COMMAND} -E make_directory "${DOXYGEN_OUTPUT_DIR}"
34+
COMMAND ${DOXYGEN_EXECUTABLE} "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile"
35+
DEPENDS ${FDB_PUBLIC_HEADERS} "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile"
36+
MAIN_DEPENDENCY "${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in"
37+
WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
38+
COMMENT "Running Doxygen on FDB API headers"
39+
)
40+
41+
# --- Sphinx ---
1442
add_custom_command(
15-
DEPENDS
16-
${FDB_PUBLIC_HEADERS}
17-
${PYFDB_SRCS}
18-
${Z3FDB_SRCS}
19-
${SPHINX_INPUT_FILES}
20-
conf.py
43+
OUTPUT ${SPHINX_INDEX_FILE}
2144
COMMAND
22-
DOXYGEN_EXECUTABLE=${DOXYGEN_EXECUTABLE}
23-
SPHINX_EXECUTABLE=${SPHINX_EXECUTABLE}
24-
DOCBUILD_OUTPUT=${CMAKE_CURRENT_BINARY_DIR}
25-
${CMAKE_CURRENT_SOURCE_DIR}/build_docs.sh
26-
MAIN_DEPENDENCY ${DOXYFILE}
27-
COMMENT "Generating documentation"
28-
OUTPUT ${SPHINX_INDEX_FILE} ${DOXYGEN_INDEX_FILE}
45+
${SPHINX_EXECUTABLE} -j auto -E -a -T
46+
-Dbreathe_projects.FDB=${DOXYGEN_XML_DIR}
47+
-Dversion=${FDB_VERSION}
48+
-Drelease=${FDB_VERSION}
49+
"${CMAKE_CURRENT_SOURCE_DIR}"
50+
"${SPHINX_OUTPUT_DIR}"
51+
DEPENDS ${DOXYGEN_INDEX_FILE} ${SPHINX_INPUT_FILES}
52+
${PYFDB_SRCS} ${Z3FDB_SRCS}
53+
"${CMAKE_CURRENT_SOURCE_DIR}/conf.py"
54+
COMMENT "Running Sphinx to build HTML documentation"
2955
)
3056

57+
# --- Target ---
3158
add_custom_target(fdb-doc ALL DEPENDS ${SPHINX_INDEX_FILE} ${DOXYGEN_INDEX_FILE})

docs/Doxyfile renamed to docs/Doxyfile.in

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ PROJECT_NAME = "Fields Database - FDB"
4848
# could be handy for archiving the generated documentation or if some version
4949
# control system is used.
5050

51-
PROJECT_NUMBER =
51+
PROJECT_NUMBER = @FDB_VERSION@
5252

5353
# Using the PROJECT_BRIEF tag one can provide an optional one line description
5454
# for a project that appears at the top of each page and should give viewers a
@@ -74,7 +74,7 @@ PROJECT_ICON =
7474
# entered, it will be relative to the location where Doxygen was started. If
7575
# left blank the current directory will be used.
7676

77-
OUTPUT_DIRECTORY = $(DOXYGEN_OUTPUT_DIR)
77+
OUTPUT_DIRECTORY = @DOXYGEN_OUTPUT_DIR@
7878

7979
# If the CREATE_SUBDIRS tag is set to YES then Doxygen will create up to 4096
8080
# sub-directories (in 2 levels) under the output directory of each output format
@@ -991,7 +991,7 @@ WARN_LOGFILE =
991991
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
992992
# Note: If this tag is empty the current directory is searched.
993993

994-
INPUT = $(DOXYGEN_INPUT_DIR)
994+
INPUT = @DOXYGEN_INPUT_DIR@
995995

996996
# This tag can be used to specify the character encoding of the source files
997997
# that Doxygen parses. Internally Doxygen uses the UTF-8 encoding. Doxygen uses

‎docs/build_docs.sh‎

Lines changed: 17 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,28 @@
11
#!/usr/bin/env bash
22
set -ex
33

4-
script_dir="$(dirname "$(readlink -f "$0")")"
5-
doxyfile="${script_dir}/Doxyfile"
6-
doxygen_executable="${DOXYGEN_EXECUTABLE:-doxygen}"
7-
sphinx_executable="${SPHINX_EXECUTABLE:-sphinx-build}"
8-
version_str=$(cat "${script_dir}/../VERSION")
4+
script_dir="$(cd "$(dirname "$0")" && pwd)"
5+
repo_root="$(cd "${script_dir}/.." && pwd)"
6+
version_str=$(cat "${repo_root}/VERSION")
97
output_dir=${DOCBUILD_OUTPUT:-doc-build}
108
doxygen_output_dir="${output_dir}/doxygen"
11-
doxygen_input_dir="${script_dir}/../src/fdb5/api"
9+
doxygen_input_dir="${repo_root}/src/fdb5/api"
1210

13-
mkdir -p "${doxygen_output_dir}"
11+
doxygen_executable="${DOXYGEN_EXECUTABLE:-doxygen}"
12+
sphinx_executable="${SPHINX_EXECUTABLE:-sphinx-build}"
1413

15-
echo "PWD=$(pwd)"
14+
# Substitute CMake @VARIABLE@ placeholders in Doxyfile.in
15+
mkdir -p "${doxygen_output_dir}"
16+
sed \
17+
-e "s|@DOXYGEN_OUTPUT_DIR@|${doxygen_output_dir}|g" \
18+
-e "s|@DOXYGEN_INPUT_DIR@|${doxygen_input_dir}|g" \
19+
-e "s|@FDB_VERSION@|${version_str}|g" \
20+
"${script_dir}/Doxyfile.in" > "${output_dir}/Doxyfile"
1621

17-
DOXYGEN_OUTPUT_DIR="${doxygen_output_dir}" \
18-
DOXYGEN_INPUT_DIR="${doxygen_input_dir}" \
19-
${doxygen_executable} ${doxyfile}
22+
${doxygen_executable} "${output_dir}/Doxyfile"
2023

2124
"${sphinx_executable}" -j auto -E -a -T \
22-
-Dbreathe_projects.FDB=$(readlink -f ${doxygen_output_dir}/xml) \
23-
-Dversion=${version_str} \
24-
-Drelease=${version_str} \
25+
-Dbreathe_projects.FDB="$(cd "${doxygen_output_dir}/xml" && pwd)" \
26+
-Dversion="${version_str}" \
27+
-Drelease="${version_str}" \
2528
"${script_dir}" "${output_dir}/sphinx"

‎docs/conf.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
# For the full list of built-in configuration values, see the documentation:
44
# https://www.sphinx-doc.org/en/master/usage/configuration.html
55
import datetime
6+
import os
67
# -- Project information -----------------------------------------------------
78
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
89

@@ -85,6 +86,7 @@
8586
html_static_path = ["_static"]
8687

8788
# -- Breathe configuration ---------------------------------------------------
89+
breathe_projects = {"FDB": os.environ.get("DOXYGEN_XML_DIR", "doxygen/xml")}
8890
breathe_default_project = "FDB"
8991

9092
# -- autosectionlabel configuration ------------------------------------------

‎docs/fdb/c_api.rst‎

Lines changed: 0 additions & 48 deletions
This file was deleted.

‎docs/fdb/cli_tools/compare.rst‎

Lines changed: 30 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
fdb-compare
1+
fdb compare
22
===========
33

44
| Compares data of two different FDBs or different data version within one FDB.
@@ -11,12 +11,16 @@ Usage
1111
-----
1212

1313
Compares two entire FDBs for MARS id equality:
14+
1415
::
16+
1517
% fdb-compare --config1=<path/to/config1.yaml> --config2=<path/to/config2.yaml> [options...]
1618

1719

1820
Compare different data in the default (production) FDB:
21+
1922
::
23+
2024
% fdb-compare --request1="..." --request2="..." [options...]
2125

2226

@@ -26,7 +30,7 @@ Options
2630
+----------------------------------------+-----------------------------------------------------------------------------------------+
2731
| ``--config1=string`` | Path to a FDB config. If not passed, FDB5 specific |
2832
| | environment variables like FDB5_CONFIG_FILE will be evaluated. If ``--config1`` |
29-
| | is not provided, ``--request1`` must be provided.i |
33+
| | is not provided, ``--request1`` must be provided. |
3034
+----------------------------------------+-----------------------------------------------------------------------------------------+
3135
| ``--config2=string`` | Optional: Path to a second different FDB config. Default: Same as ``--config1`` |
3236
| | (if passed), otherwise FDB5 specific environment variables are evaluated. |
@@ -38,18 +42,19 @@ Options
3842
+----------------------------------------+-----------------------------------------------------------------------------------------+
3943
| ``--request2=string`` | Optional: Specialized mars keys to request different data from the second FDB, |
4044
| | e.g. ``--request2="class=od,expver=abcd".`` |
41-
| | Allows comparing different MARS subtrees. Only valid if ``--request1` has ben specified.|
45+
| | Allows comparing different MARS subtrees. |
46+
| | Only valid if ``--request1`` has been specified. |
4247
+----------------------------------------+-----------------------------------------------------------------------------------------+
43-
| ``--scope=string`` | Optional - Values: ``[mars (default)|header-only|all]`` |
44-
| | The FDBs can be compared in different scopes, |
45-
| | 1) ``[mars]`` Mars Metadata only (default), |
46-
| | 2) ``[header-only]`` includes Mars Key comparison |
47-
| | and the comparison of the data headers (e.g. grib headers). |
48-
| | Note: with ``grib-comparison-type=bit-identical``, the full message is |
49-
| | still compared byte-for-byte; ``header-only`` filtering only applies |
50-
| | to ``grib-keys`` comparison. |
51-
| | 3) ``[all]`` includes Mars key and data header comparison but also |
52-
| | the data sections up to a defined floating point tolerance. |
48+
| ``--scope=string`` | Optional - Values: ``[mars (default) / header-only / all]`` |
49+
| | The FDBs can be compared in different scopes: |
50+
| | 1) ``mars`` Mars Metadata only (default), |
51+
| | 2) ``header-only`` includes Mars Key comparison and the comparison |
52+
| | of the data headers (e.g. grib headers). Note: with |
53+
| | ``grib-comparison-type=bit-identical``, the full message is still |
54+
| | compared byte-for-byte; ``header-only`` filtering only applies to |
55+
| | ``grib-keys`` comparison. |
56+
| | 3) ``all`` includes Mars key and data header comparison but also |
57+
| | the data sections up to a defined floating point tolerance. |
5358
+----------------------------------------+-----------------------------------------------------------------------------------------+
5459
| ``--grib-comparison-type=string`` | Optional - Values: ``[hash-keys|grib-keys(default)|bit-identical]`` |
5560
| | Comparing two Grib messages can be done via either (``grib-comparison-type=hash-keys``) |
@@ -79,21 +84,29 @@ Options
7984
Examples
8085
--------
8186

82-
Compares two entire FDBs for equality. Using the `--scope=all` options, not only the headers but also the data is compared:
87+
Compares two entire FDBs for equality. Using the ``--scope=all`` option, not only the headers but also the data is compared:
88+
8389
::
90+
8491
% fdb-compare --config1=<path/to/config1.yaml> --config2=<path/to/config2.yaml> --scope=all
8592

8693
Compares a specific part (class=rd,expver=1234) of two different FDBs for equality:
94+
8795
::
96+
8897
% fdb-compare --config1=<path/to/config1.yaml> --config2=<path/to/config2.yaml> --request1="class=rd,expver=1234"
8998

9099

91-
Compares different data versions within one FDB using ``--request1`` and ``--request2``. In that case the only usable ``--grib-comparison-type`` is `grib-keys` (the default option):
100+
Compares different data versions within one FDB using ``--request1`` and ``--request2``. In that case the only usable ``--grib-comparison-type`` is ``grib-keys`` (the default option):
101+
92102
::
103+
93104
% fdb-compare --config1=<path/to/config1.yaml> --request1="class=od,expver=abcd" --request2="class=rd,expver=1234" --grib-comparison-type="grib-keys" | tee out
94105

95106
Compares different data versions within the production FDB if executed on ATOS (the FDB5 config will be inferred from the environment):
107+
96108
::
109+
97110
% fdb-compare --request1="class=od,expver=abcd" --request2="class=rd,expver=1234" --grib-comparison-type="grib-keys" | tee out
98111

99112

@@ -107,7 +120,7 @@ The tool exits with code **0** on success (all compared entries match) and **non
107120
Notes
108121
-----
109122

110-
When comparing within a single FDB (using ``--config1`` is enough).
111-
Minimum arguments are either ``--config1`` or ``--request1``. This is explicitly checked,
123+
When comparing within a single FDB, using ``--config1`` is enough.
124+
Minimum arguments are either ``--config1`` or ``--request1``. This is explicitly checked,
112125
otherwise the default behaviour would result in a comparison of the default FDB (prodfdb on ATOS) with itself.
113126

docs/fdb/content/DebugTools/dump-index.rst renamed to docs/fdb/cli_tools/dump-index.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ fdb dump-index
44
Dump the contents of a particular index file for debugging purposes.
55

66
Note that one index file can (and likely will) contain multiple indexes, which will be dumped sequentially.
7+
78
Usage
89
-----
910

@@ -12,6 +13,8 @@ Usage
1213
Options
1314
-------
1415

16+
This tool has no tool-specific options. It accepts only positional path arguments.
17+
1518
Examples
1619
--------
1720

docs/fdb/content/DebugTools/dump-toc.rst renamed to docs/fdb/cli_tools/dump-toc.rst

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,13 @@ Usage
1414
Options
1515
-------
1616

17-
+----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
18-
| ``--walk`` | Walk through tocs any linked subtocs in logically correct view. This displays the contents presented by any linked subtocs, and masks any masked entries, to show the contents as would be presented to the user.|
19-
+----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
20-
| ``--config=string`` | FDB configuration filename. |
21-
+----------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
17+
+----------------------------------------+-----------------------------------------------------------------------------------------+
18+
| ``--walk`` | | Walk through tocs and any linked subtocs in logically correct view. |
19+
| | | This displays the contents presented by any linked subtocs, and masks any |
20+
| | | masked entries, to show the contents as would be presented to the user. |
21+
+----------------------------------------+-----------------------------------------------------------------------------------------+
22+
| ``--structure`` | Add toc record lengths and offsets to output |
23+
+----------------------------------------+-----------------------------------------------------------------------------------------+
2224

2325
Examples
2426
--------

docs/fdb/content/DebugTools/dump.rst renamed to docs/fdb/cli_tools/dump.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Options
1414
-------
1515

1616
+----------------------------------------+---------------------------------------------------------------------------------------------------------------------+
17-
| ``--simple`` | Also print the location of each field |
17+
| ``--simple`` | Provide a more concise, single-line output |
1818
+----------------------------------------+---------------------------------------------------------------------------------------------------------------------+
1919
| ``--ignore-errors`` | Ignore errors (report them as warnings) and continue processing wherever possible |
2020
+----------------------------------------+---------------------------------------------------------------------------------------------------------------------+

docs/fdb/content/GeneralPurposeTools/fdb-stats.rst renamed to docs/fdb/cli_tools/fdb-stats.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ You may pass a partial request (as a key) that will print information on all FDB
4848
Size of fields : 3,542,829,840 (3.29952 Gbytes)
4949
Duplicated fields : 1,056
5050
Size of duplicates : 3,464,100,288 (3.22619 Gbytes)
51-
Reacheable fields : 24
51+
Reachable fields : 24
5252
Reachable size : 78,729,552 (75.0824 Mbytes)
5353
TOC records : 46
5454
Size of TOC files : 47,104 (46 Kbytes)
@@ -77,7 +77,7 @@ The --details flag prints a report per database that is visited, as well as the
7777
Size of fields : 20,784,601,728 (19.3572 Gbytes)
7878
Duplicated fields : 6,240
7979
Size of duplicates : 20,469,683,520 (19.0639 Gbytes)
80-
Reacheable fields : 96
80+
Reachable fields : 96
8181
Reachable size : 314,918,208 (300.329 Mbytes)
8282
TOC records : 268
8383
Size of TOC files : 274,432 (268 Kbytes)

0 commit comments

Comments
 (0)