Skip to content

Commit 34620c8

Browse files
SharafMohamedLinZhihao-723davidlionkirkrodrigues
authored
docs: Add support for generating a documentation site through Doxygen. (#133)
Co-authored-by: Lin Zhihao <[email protected]> Co-authored-by: davidlion <[email protected]> Co-authored-by: SharafMohamed <[email protected]> Co-authored-by: kirkrodrigues <[email protected]>
1 parent c954252 commit 34620c8

File tree

15 files changed

+537
-109
lines changed

15 files changed

+537
-109
lines changed

‎.github/workflows/docs.yaml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
name: "docs"
2+
3+
on:
4+
pull_request:
5+
push:
6+
schedule:
7+
# Run daily at 00:15 UTC (the 15 is to avoid periods of high load)
8+
- cron: "15 0 * * *"
9+
workflow_dispatch:
10+
11+
concurrency:
12+
group: "${{github.workflow}}-${{github.ref}}"
13+
14+
# Cancel in-progress jobs for efficiency
15+
cancel-in-progress: true
16+
17+
jobs:
18+
build:
19+
name: "Build docs site"
20+
runs-on: "ubuntu-latest"
21+
steps:
22+
- uses: "actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683"
23+
with:
24+
lfs: "true"
25+
submodules: "recursive"
26+
27+
- name: "Install task"
28+
shell: "bash"
29+
run: "npm install -g @go-task/cli"
30+
31+
- name: "Build docs"
32+
shell: "bash"
33+
run: "task docs:site"
34+
35+
# Upload the built docs site if we need to debug any issues
36+
- if: >-
37+
contains(fromJSON('["push", "workflow_dispatch"]'), github.event_name)
38+
&& ('refs/heads/main' == github.ref || startsWith(github.ref, 'refs/tags/v'))
39+
uses: "actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02"
40+
with:
41+
name: "docs-html"
42+
path: "build/docs/html"
43+
if-no-files-found: "error"
44+
45+
# Retain the artifact for a week
46+
retention-days: 7

‎README.md‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -109,13 +109,32 @@ To build the debug version:
109109
task build:debug
110110
```
111111

112-
## Documentation and examples
112+
## Examples
113+
114+
[examples](examples) contains programs demonstrating usage of the library. See
115+
[examples/README.md](examples/README.md) for information on building and running the examples.
116+
117+
## Documentation
113118

114119
* [docs](docs) contains more detailed documentation including:
115120
* The [schema specification](docs/schema.md), which describes the syntax for
116121
writing your own schema
117122
* `log-surgeon`'s [design objectives](docs/design-objectives.md)
118-
* [examples](examples) contains programs demonstrating usage of the library.
123+
124+
### Documentation site
125+
126+
The project includes a documentation site that's useful for exploring functionality and test
127+
coverage. In particular, it documents all unit tests, with additional detail for API-level tests.
128+
129+
To generate and view the files:
130+
131+
* Run `task docs:site`.
132+
* Open `build/docs/html/index.html` in your preferred browser.
133+
134+
To host the site locally and view it:
135+
136+
* Run `task docs:serve`.
137+
* Open the URL output by the task in your preferred browser.
119138

120139
## Testing
121140

‎docs/doxygen/Doxyfile‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Project information
2+
PROJECT_BRIEF = "Test & API docs"
3+
PROJECT_NAME = "Log Surgeon"
4+
OUTPUT_DIRECTORY = build/docs/
5+
6+
# Input
7+
INPUT = \
8+
docs/doxygen/mainpage.dox \
9+
tests/
10+
RECURSIVE = YES
11+
12+
# Source code parsing
13+
EXTRACT_ALL = YES
14+
EXTRACT_PRIVATE = YES
15+
EXTRACT_STATIC = YES
16+
MACRO_EXPANSION = YES
17+
PREDEFINED = "TEST_CASE(x,y)=void x()"
18+
19+
# Output
20+
GENERATE_LATEX = NO
21+
HTML_DYNAMIC_SECTIONS = YES
22+
TIMESTAMP = YES
23+
24+
# Misc
25+
WARN_AS_ERROR = YES

‎docs/doxygen/mainpage.dox‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
/** @mainpage
2+
*
3+
* # Use case examples of schema rules and parsing results:
4+
*
5+
* - @ref test_buffer_parser_no_capture "Basic log parser"
6+
* - @ref test_buffer_parser_capture "Captures"
7+
* - @ref test_buffer_parser_default_schema "Default CLP schema"
8+
* - @ref test_buffer_parser_delimited_variables "Backtracking on delimited variables"
9+
* - @ref test_buffer_parser_newline_vars "Identifying variables at the start of a line"
10+
*
11+
* # Unit-tests:
12+
*
13+
* - @ref unit_tests_capture "Capture"
14+
* - @ref unit_tests_dfa "DFA"
15+
* - @ref unit_tests_nfa "NFA"
16+
* - @ref unit_tests_prefix_tree "Prefix tree"
17+
* - @ref unit_tests_regex_ast "Regex AST"
18+
* - @ref unit_tests_register_handler "Register handler"
19+
* - @ref unit_tests_schema "Schema"
20+
*/

‎taskfile.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ shopt: ["globstar"]
66
includes:
77
build: "taskfiles/build.yaml"
88
deps: "taskfiles/deps.yaml"
9+
docs: "taskfiles/docs.yaml"
910
lint: "taskfiles/lint.yaml"
1011
test: "taskfiles/test.yaml"
1112

‎taskfiles/docs.yaml‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
version: "3"
2+
3+
includes:
4+
utils:
5+
internal: true
6+
taskfile: "../tools/yscope-dev-utils/exports/taskfiles/utils/utils.yaml"
7+
8+
vars:
9+
# General paths
10+
G_DOCS_BUILD_DIR: "{{.G_BUILD_DIR}}/docs"
11+
G_DOCS_HTML_DIR: "{{.G_DOCS_BUILD_DIR}}/html"
12+
G_DOCS_VENV_DIR: "{{.G_DOCS_BUILD_DIR}}/docs-venv"
13+
G_NODE_DEPS_DIR: "{{.G_DOCS_BUILD_DIR}}/docs-node"
14+
15+
# Doxygen paths
16+
G_DOXYFILE_PATH: "{{.ROOT_DIR}}/docs/doxygen/Doxyfile"
17+
G_DOXYGEN_CMD: "{{.G_DOCS_VENV_DIR}}/bin/doxygen"
18+
19+
tasks:
20+
clean:
21+
cmds:
22+
- "rm -rf '{{.G_DOCS_BUILD_DIR}}'"
23+
24+
serve:
25+
deps:
26+
- "http-server"
27+
- "site"
28+
cmds:
29+
- "npm --prefix '{{.G_NODE_DEPS_DIR}}' exec -- http-server '{{.G_DOCS_HTML_DIR}}' -c-1"
30+
31+
site:
32+
vars:
33+
CHECKSUM_FILE: "{{.G_BUILD_DIR}}/{{.TASK | replace \":\" \"#\"}}.md5"
34+
OUTPUT_DIR: "{{.G_DOCS_HTML_DIR}}"
35+
sources:
36+
- "{{.G_DOXYFILE_PATH}}"
37+
- "{{.ROOT_DIR}}/docs/**/*"
38+
- "{{.ROOT_DIR}}/src/**/*"
39+
- "{{.ROOT_DIR}}/taskfile.yaml"
40+
- "{{.ROOT_DIR}}/tests/**/*"
41+
- "{{.TASKFILE}}"
42+
generates: ["{{.CHECKSUM_FILE}}"]
43+
deps:
44+
- task: "utils:checksum:validate"
45+
vars:
46+
CHECKSUM_FILE: "{{.CHECKSUM_FILE}}"
47+
INCLUDE_PATTERNS: ["{{.OUTPUT_DIR}}"]
48+
- "venv"
49+
cmds:
50+
- |-
51+
rm -rf "{{.G_DOCS_HTML_DIR}}"
52+
cd "{{.ROOT_DIR}}"
53+
"{{.G_DOXYGEN_CMD}}" "{{.G_DOXYFILE_PATH}}"
54+
55+
# This command must be last
56+
- task: "utils:checksum:compute"
57+
vars:
58+
CHECKSUM_FILE: "{{.CHECKSUM_FILE}}"
59+
INCLUDE_PATTERNS: ["{{.OUTPUT_DIR}}"]
60+
61+
http-server:
62+
internal: true
63+
run: "once"
64+
vars:
65+
CHECKSUM_FILE: "{{.G_BUILD_DIR}}/{{.TASK | replace \":\" \"#\"}}.md5"
66+
OUTPUT_DIR: "{{.G_NODE_DEPS_DIR}}"
67+
sources:
68+
- "{{.ROOT_DIR}}/taskfile.yaml"
69+
- "{{.TASKFILE}}"
70+
generates: ["{{.CHECKSUM_FILE}}"]
71+
deps:
72+
- ":init"
73+
- task: "utils:checksum:validate"
74+
vars:
75+
CHECKSUM_FILE: "{{.CHECKSUM_FILE}}"
76+
INCLUDE_PATTERNS: ["{{.OUTPUT_DIR}}"]
77+
cmds:
78+
- "rm -rf '{{.OUTPUT_DIR}}'"
79+
- "npm --prefix '{{.OUTPUT_DIR}}' install http-server"
80+
81+
# This command must be last
82+
- task: "utils:checksum:compute"
83+
vars:
84+
CHECKSUM_FILE: "{{.CHECKSUM_FILE}}"
85+
INCLUDE_PATTERNS: ["{{.OUTPUT_DIR}}"]
86+
87+
venv:
88+
internal: true
89+
run: "once"
90+
vars:
91+
DOXYGEN_FILENAME: "doxygen-1.14.0.linux.bin.tar.gz"
92+
deps:
93+
- ":init"
94+
cmds:
95+
- "mkdir -p '{{.G_DOCS_VENV_DIR}}'"
96+
- task: "utils:remote:download-and-extract-tar"
97+
vars:
98+
FILE_SHA256: "e5d6ae24d0bf3f0cdc4d8f146726b89ca323922f19441af99b1872d503665ad6"
99+
INCLUDE_PATTERNS:
100+
- "bin"
101+
OUTPUT_DIR: "{{.G_DOCS_VENV_DIR}}"
102+
TAR_FILE: "{{.G_DOCS_BUILD_DIR}}/{{.DOXYGEN_FILENAME}}"
103+
URL: "https://www.doxygen.nl/files/{{.DOXYGEN_FILENAME}}"

‎taskfiles/lint.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ tasks:
6262
.github \
6363
.clang-format \
6464
taskfile.yaml \
65+
taskfiles/docs.yaml \
6566
{{.TASKFILE}}
6667
6768
cpp:

0 commit comments

Comments
 (0)