search

JuliaPOMDP / POMDPs.jl

MDPs and POMDPs in Julia - An interface for defining, solving, and simulating fully and partially observable Markov decision processes on discrete and continuous spaces.
http://juliapomdp.github.io/POMDPs.jl/latest/
Other
652 stars 99 forks source link

Update docs to incorporate POMDPExamples and POMDPGallery #539

Closed dylan-asmar closed 4 months ago

dylan-asmar commented 5 months ago

I have updated the documentation to incorporate the content from POMDPExamples.jl and POMDPGallery.jl.

I tried to use @example blocks so the examples and gallery images should be generated during the generation of the documentation. The idea here was to have up-to-date examples each time the documentation was generated. It also adds another layer of implicit tests as the examples and gallery use various portions of the interface.

I followed the Examples and Gallery repos closely, with deviations when there appeared to be redundant information already in the documentation somewhere.

Of note, I did not include ContinuumWorld, LaserTag, or VDPTag2 in the gallery section due to problems/issues with those repositories.

I also did not include the notebooks referenced in the "Legacy tutorials" section of POMDPExamples.jl.

Issues this PR addresses:

dylan-asmar commented 5 months ago

Preview of the docs: https://juliapomdp.github.io/POMDPs.jl/previews/PR539/

@mykelk @mossr @zsunberg , any suggested changes/updates?

dylan-asmar commented 5 months ago

All of the examples and code are run within the documentation pipeline. I didn't structure them using jldoctest, but used @example blocks (julia documentation link). I initially thought to use jldoctest, but I didn't think matching the expected output exactly was as important as showing working examples that stay up to date (or cause an error if something breaks). As far as maintainability, it should be rather minimal as the @example blocks evaluate the code and inserts the result into the documentation.

Right now, I use the POMDPs generated in the "Defining a POMDP" section later in the documentation (solvers and simulation examples). Ideally, we could just use the code directly. However, since they are on different pages, I didn't find a way to build upon the code executed from another page.

According to the @example documentation:

By default @example blocks are run in their own anonymous Modules to avoid side-effects between blocks. To share the same module between different blocks on a page the @example can be named with the following syntax ...

Thus the way to work around this was to include crying_baby_examples.jl and crying_baby_solvers.jl in the examples directory and then call them as a setup block for @example blocks later on the same page. This unfortunately results in the requirement that any updates to the defining a POMDP code or solvers code (unlikely for the latter) require an update to the supporting files (crying_baby_example.jl and/or crying_baby_solvers.jl).

I wasn't sure how, but if we could pull code directly into the documentation in an @example or jldoctest block, then we could reduce the redundant code. Another option might be to save these supporting files real-time when the blocks are executed. However, both of these ideas would require a bit more time (that I didn't have) to research on how to do it properly.

zsunberg commented 4 months ago

Sorry for the delay. This semester is crazy for me! This is great - thank you so much @dylan-asmar , this is a huge contribution.