Skip to content

Commit 796a448

Browse files
ocotsocots
authored
Merge pull request #383 from control-toolbox/cleaning
Refactor documentation and remove CTBaseDocstrings extension
2 parents a600654 + 6cd444e commit 796a448

30 files changed

+1834
-1475
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)