Update docs to incorporate POMDPExamples and POMDPGallery

[dylan-asmar]

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.

• ContinuumWorld: CWorldSolver ContinuumWorld.jl#5
• LaserTag: Issues with latex rendering with GitHub actions (more than likely a "me" problem)
• VDPTag2: Visualization not compatible with POMDPs.jl ecosystem zsunberg/VDPTag2.jl#16

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

Issues this PR addresses:

• Resolves Move simulation examples from POMDPExamples to main documentation #417
• Addresses Documentation urls leading to missing page #360 (the first link is up to date in most recent MCTS documentation and the second one isn't a factor after the change)
• I think it resolves The documentation is scattered #324 as well

[dylan-asmar]

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

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

[zsunberg]

Wow @dylan-asmar thanks so much for this huge contribution! I apologize for taking so long to look at it. My travel this week put me behind on email.

I wasn't able to look at it super closely, but it looked good for the most part. I added a couple comments inline, but I have one big question: does all of the code get run in the doctests? it will be much easier to maintain if that is the case!

Also, we can tag a new +docs version - let me know if you have trouble figuring that out.

[zsunberg]

I think there is a better way to make these links relative - maybe [Examples](/examples) or something. We don't really want to always point to a hand coded url and the latest version.

[dylan-asmar]

I know you can make relative links in the documentation. I wasn't aware you could do it from the README.md to the documentation. I'll look into that. I agree that it would be the better way to go.

[zsunberg]

Is this redundant with the defining a POMDP example file above?

[dylan-asmar]

Yes and kind of no. I included some more details in a follow-up comment.

[dylan-asmar]

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]

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