Skip to content

Commit afc2e06

Browse files
ocotsocots
committed
Refactor documentation and remove CTBaseDocstrings extension
- Replace CTBaseDocstrings extension with DocumenterReference extension - Simplify docs structure by consolidating pages into index.md - Update docstrings with proper CTBase namespace references - Add examples to utility functions in utils.jl - Remove deprecated doc_app.jl, docstrings.jl, and prompt.jl - Update Project.toml dependencies - Add markdownlint and VSCode ltex configuration
1 parent a600654 commit afc2e06

22 files changed

+972
-1322
lines changed

‎.markdownlint.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"MD046": false,
3+
"MD013": false
4+
}

‎.vscode/ltex.dictionary.en-US.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
OptimalControl
2+
CTBase

‎.vscode/ltex.hiddenFalsePositives.en-US.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{"rule":"MORFOLOGIK_RULE_EN_US","sentence":"^\\QThe root package is OptimalControl.jl which aims to provide tools to model and solve optimal control problems with ordinary differential equations by direct and indirect methods, both on CPU and GPU.\\E$"}
2+
{"rule":"UPPERCASE_SENTENCE_START","sentence":"^\\Qwarning\\E$"}
3+
{"rule":"MORFOLOGIK_RULE_EN_US","sentence":"^\\QCTBase.jl\\E$"}

‎Project.toml‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,22 @@
11
name = "CTBase"
22
uuid = "54762871-cc72-4466-b8e8-f6c8b58076cd"
3+
version = "0.17.0"
34
authors = ["Olivier Cots <olivier.cots@irit.fr>", "Jean-Baptiste Caillau <caillau@univ-cotedazur.fr>"]
4-
version = "0.16.4"
55

66
[deps]
77
DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
88

99
[weakdeps]
10-
HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3"
11-
JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
10+
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
11+
Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
12+
MarkdownAST = "d0879d2d-cac2-40c8-9cee-1863dc0c7391"
1213

1314
[extensions]
14-
CTBaseDocstrings = ["HTTP","JSON"]
15+
DocumenterReference = ["Documenter", "MarkdownAST", "Markdown"]
1516

1617
[compat]
1718
DocStringExtensions = "0.9"
18-
HTTP = "1"
19-
JSON = "1"
19+
Documenter = "1"
20+
Markdown = "1"
21+
MarkdownAST = "0.1"
2022
julia = "1.10"

‎docs/Project.toml‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,8 @@
11
[deps]
22
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
3-
DocumenterMermaid = "a078cd44-4d9c-4618-b545-3ab9d77f9177"
4-
HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3"
5-
JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
3+
MarkdownAST = "d0879d2d-cac2-40c8-9cee-1863dc0c7391"
64

75
[compat]
86
Documenter = "1"
9-
DocumenterMermaid = "0.2"
10-
HTTP = "1"
11-
JSON = "1"
7+
MarkdownAST = "0.1"
8+
julia = "1.10"

‎docs/make.jl‎

Lines changed: 84 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,36 @@
11
using Documenter
22
using CTBase
3-
using DocumenterMermaid
4-
using HTTP, JSON
3+
using Markdown
4+
using MarkdownAST: MarkdownAST
55

6-
const CTBaseDocstrings = Base.get_extension(CTBase, :CTBaseDocstrings)
6+
# ═══════════════════════════════════════════════════════════════════════════════
7+
# Configuration
8+
# ═══════════════════════════════════════════════════════════════════════════════
9+
draft = false # Draft mode: if true, @example blocks in markdown are not executed
10+
11+
# ═══════════════════════════════════════════════════════════════════════════════
12+
# Docstrings from external packages
13+
# ═══════════════════════════════════════════════════════════════════════════════
14+
const DocumenterReference = Base.get_extension(CTBase, :DocumenterReference)
715

8-
# to add docstrings from external packages
916
Modules = [Base]
1017
for Module in Modules
1118
isnothing(DocMeta.getdocmeta(Module, :DocTestSetup)) &&
1219
DocMeta.setdocmeta!(Module, :DocTestSetup, :(using $Module); recursive=true)
1320
end
1421

22+
# ═══════════════════════════════════════════════════════════════════════════════
23+
# Repository configuration
24+
# ═══════════════════════════════════════════════════════════════════════════════
1525
repo_url = "github.com/control-toolbox/CTBase.jl"
1626

17-
API_PAGES = ["ctbase.md", "default.md", "description.md", "docstrings.md", "exception.md"]
18-
27+
# ═══════════════════════════════════════════════════════════════════════════════
28+
# Build documentation
29+
# ═══════════════════════════════════════════════════════════════════════════════
1930
makedocs(;
20-
warnonly=[:cross_references, :autodocs_block],
31+
draft=draft,
32+
remotes=nothing, # Disable remote links. Needed for DocumenterReference
33+
warnonly=true,
2134
sitename="CTBase.jl",
2235
format=Documenter.HTML(;
2336
repolink="https://" * repo_url,
@@ -28,8 +41,71 @@ makedocs(;
2841
asset("https://control-toolbox.org/assets/js/documentation.js"),
2942
],
3043
),
31-
pages=["Introduction" => "index.md", "API" => API_PAGES],
44+
pages=[
45+
"Introduction" => "index.md",
46+
"API Reference" => [
47+
CTBase.automatic_reference_documentation(;
48+
subdirectory=".",
49+
modules=[CTBase],
50+
exclude=Symbol[:include, :eval],
51+
public=false,
52+
private=true,
53+
title="CTBase",
54+
title_in_menu="CTBase", # optionnel
55+
filename="ctbase",
56+
source_files=[abspath(joinpath(@__DIR__, "..", "src", "CTBase.jl"))],
57+
),
58+
CTBase.automatic_reference_documentation(;
59+
subdirectory=".",
60+
modules=[CTBase],
61+
exclude=Symbol[:include, :eval],
62+
public=false,
63+
private=true,
64+
title="Default",
65+
title_in_menu="Default", # optionnel
66+
filename="default",
67+
source_files=[abspath(joinpath(@__DIR__, "..", "src", "default.jl"))],
68+
),
69+
CTBase.automatic_reference_documentation(;
70+
subdirectory=".",
71+
modules=[CTBase],
72+
exclude=Symbol[:include, :eval],
73+
public=false,
74+
private=true,
75+
title="Description",
76+
title_in_menu="Description", # optionnel
77+
filename="description",
78+
source_files=[abspath(joinpath(@__DIR__, "..", "src", "description.jl"))],
79+
),
80+
CTBase.automatic_reference_documentation(;
81+
subdirectory=".",
82+
modules=[CTBase],
83+
doc_modules=[Base], # pour inclure Base.showerror
84+
exclude=Symbol[:include, :eval],
85+
public=false,
86+
private=true,
87+
title="Exception",
88+
title_in_menu="Exception", # optionnel
89+
filename="exception",
90+
source_files=[abspath(joinpath(@__DIR__, "..", "src", "exception.jl"))],
91+
),
92+
CTBase.automatic_reference_documentation(;
93+
subdirectory=".",
94+
modules=[CTBase],
95+
exclude=Symbol[:include, :eval],
96+
public=false,
97+
private=true,
98+
title="Utils",
99+
title_in_menu="Utils", # optionnel
100+
filename="utils",
101+
source_files=[abspath(joinpath(@__DIR__, "..", "src", "utils.jl"))],
102+
),
103+
],
104+
],
32105
checkdocs=:none,
33106
)
34107

108+
# ═══════════════════════════════════════════════════════════════════════════════
109+
# Deploy documentation to GitHub Pages
110+
# ═══════════════════════════════════════════════════════════════════════════════
35111
deploydocs(; repo=repo_url * ".git", devbranch="main")

‎docs/src/ctbase.md‎

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

‎docs/src/default.md‎

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

‎docs/src/description.md‎

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

‎docs/src/docstrings.md‎

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

0 commit comments

Comments
 (0)