Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs outline generation #566

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update docs outline generation #566

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
137 changes: 80 additions & 57 deletions docs/make.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,71 +2,94 @@ push!(LOAD_PATH, "../src/")

using Documenter, POMDPs, POMDPTools

makedocs(
modules = [POMDPs, POMDPTools],
format = Documenter.HTML(),
sitename = "POMDPs.jl",
pages = [
##############################################
## MAKE SURE TO SYNC WITH docs/src/index.md ##
##############################################
"Basics" => [
"index.md",
"install.md",
"get_started.md",
"concepts.md"
],

"Defining (PO)MDP Models" => [
"def_pomdp.md",
"interfaces.md",
],

"Writing Solvers" => [
"def_solver.md",
"offline_solver.md",
"online_solver.md"
],

"Writing Belief Updaters" => [
"def_updater.md"
],
page_order = [
"POMDPs.jl" => "index.md",
"Basics" => [
"install.md",
"get_started.md",
"concepts.md"
],
"Defining (PO)MDP Models" => [
"def_pomdp.md",
"interfaces.md"
],
"Writing Solvers" => [
"def_solver.md",
"offline_solver.md",
"online_solver.md"
],
"Writing Belief Updaters" => [
"def_updater.md"
],
"Analyzing Results" => [
"simulation.md",
"run_simulation.md",
"policy_interaction.md"
],
"Examples and Gallery" => [
"examples.md",
"example_defining_problems.md",
"example_solvers.md",
"example_simulations.md",
"example_gridworld_mdp.md",
"gallery.md"
],
"POMDPTools" => [
"POMDPTools/index.md",
"POMDPTools/distributions.md",
"POMDPTools/model.md",
"POMDPTools/visualization.md",
"POMDPTools/beliefs.md",
"POMDPTools/policies.md",
"POMDPTools/simulators.md",
"POMDPTools/common_rl.md",
"POMDPTools/testing.md"
],
"References" => [
"faq.md",
"api.md"
]
]

"Analyzing Results" => [
"simulation.md",
"run_simulation.md",
"policy_interaction.md"
],

"Examples and Gallery" => [
"examples.md",
"example_defining_problems.md",
"example_solvers.md",
"example_simulations.md",
"example_gridworld_mdp.md",
"gallery.md"
],
# Append the @contents blocks to the index.md file
index_md_file = joinpath(@__DIR__, "src", "index.md")

"POMDPTools" => [
"POMDPTools/index.md",
"POMDPTools/distributions.md",
"POMDPTools/model.md",
"POMDPTools/visualization.md",
"POMDPTools/beliefs.md",
"POMDPTools/policies.md",
"POMDPTools/simulators.md",
"POMDPTools/common_rl.md",
"POMDPTools/testing.md"
],
# Copy original index.md to restore it after the build
original_index_md_file = joinpath(@__DIR__, "src", "original_index.md")
cp(index_md_file, original_index_md_file)

"faq.md",
"api.md",
open(index_md_file, "a") do f
write(f, "\n\n")
# Loop over the sections and generate a @contents block for each.
for (section, pages) in page_order
if section isa String && pages isa Vector{String} # Only sections with pages
write(f, "### $(section)\n\n")
write(f, "```@contents\n")
write(f, "Pages = $(pages)\n")
if section == "Defining (PO)MDP Models"
write(f, "Depth = 3\n")
else
write(f, "Depth = 2\n")
end
write(f, "```\n\n")
end
end
end

],
makedocs(
modules = [POMDPs, POMDPTools],
format = Documenter.HTML(),
sitename = "POMDPs.jl",
pages = page_order,
warnonly = [:missing_docs]
)

deploydocs(
repo = "github.com/JuliaPOMDP/POMDPs.jl.git",
push_preview=true
)

# Restore the original index.md file
if isfile(original_index_md_file)
mv(original_index_md_file, index_md_file, force=true)
end
46 changes: 0 additions & 46 deletions docs/src/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,49 +20,3 @@ Documentation comes in three forms:
1. An explanatory guide is available in the sections outlined below.
2. How-to examples are available throughout this documentation with specicic examples in [Examples](@ref examples_section) and [Gallery of POMDPs.jl Problems](@ref).
3. Reference docstrings for the entire POMDPs.jl interface are available in the [API Documentation](@ref) section.

!!! note
When updating these documents, make sure this is synced with [docs/make.jl](https://github.com/JuliaPOMDP/POMDPs.jl/blob/master/docs/make.jl)!!

### Basics

```@contents
Pages = ["install.md", "get_started.md", "concepts.md"]
```

### Defining POMDP Models

```@contents
Pages = [ "def_pomdp.md", "interfaces.md"]
Depth = 3
```

### Writing Solvers and Updaters

```@contents
Pages = [ "def_solver.md", "offline_solver.md", "online_solver.md", "def_updater.md" ]
```

### Analyzing Results

```@contents
Pages = [ "simulation.md", "run_simulation.md", "policy_interaction.md" ]
```

### Examples and Gallery

```@contents
Pages = [ "examples.md", "example_defining_problems.md", "example_solvers.md", "example_simulations.md", "example_gridworld_mdp.md", "gallery.md"]
```

### POMDPTools - the standard library for POMDPs.jl

```@contents
Pages = ["POMDPTools/index.md", "POMDPTools/distributions.md", "POMDPTools/model.md", "POMDPTools/visualization.md", "POMDPTools/beliefs.md", "POMDPTools/policies.md", "POMDPTools/simulators.md", "POMDPTools/common_rl.md", "POMDPTools/testing.md"]
```

### Reference

```@contents
Pages = ["faq.md", "api.md"]
```
Loading