Agents.jl: Proposal: Refactor documentation to use the examples of `examples`, Literate.jl and Documenter.jl

[Datseris]

I have a proposal to make, which will take some effort but it won't bring new features to Agents.jl. Nevertheless, I think it is worth it.

The proposal is to refactor the examples part of the documentation, so that instead of being static code, to be real Julia code that runs and whose output is shown in the documentation. This has the following benefits:

1. It ensures that the code is runnable. If it isn't the docs won't build properly.
2. It ensures that everything is up to date.
3. It also makes it easier to update the documentation after an update on the code, or when changing a parameter.
4. The examples folder is used directly in the documentation.

Here is how this works. We do it in TimeseriesPrediction.jl. We have some examples here:
https://github.com/JuliaDynamics/TimeseriesPrediction.jl/tree/master/examples
These examples are valid Julia code, which is runnable. They follow the Literate.jl syntax, which means Literate can process then and make them markdown files for the docs. Then in the make.jl we first convert them to markdown, and then documenter makes the doc page.

Here is how it looks: https://juliadynamics.github.io/TimeseriesPrediction.jl/latest/stexamples/

In the TimeseriesPrediction example we do one extra step to include all examples in a single file; I think here this should be avoided and each example should stay a separate file. So don't mind the function replace_includes

I can contribute here once the JOSS review is over.

[def-mycroft]

refactor the examples part of the documentation, so that instead of being static code, to be real Julia code that runs and whose output is shown in the documentation.

I think this is really important and I love the way it looks in the examples that you provided!!

I've been in the middle of working on some documentation edits and have been working to create a correspondence between the examples and the documentation page.

I had been working on the Boltzmann example before you made this post and will try to finish soon (was sidetracked on another project last week).

So I think what I'll do (unless there is a better idea) is continue to refactor the examples like I have been, and then after there is a tight correspondence between the docs pages the scripts in examples/ it will be easier to upgrade to using Literate.jl.

[Datseris]

Cool, happy to see you liking the idea! Don't forget that this is something I can easily contribute to after the JOSS review is done, since I have already done it a couple of times for various doc pages (e.g. also JuliaMusic).

[kavir1698]

It is efficient to integrate the examples folder into the docs. It saves a lot of redundancy.

[Datseris]

Still waiting for the JOSS review to be done, to avoid conflict of interests....

[Datseris]

I am currently working on this, but it will simplify the code a lot if #24 is solved as well.

[kavir1698]

Thank you, George. I am too busy teaching a course nowadays. I will have time to work on it in November.

[Datseris]

This has been done by me for the Forest fire example, one can see it in the examples/forest_fire.jl and how it is converted in the docs/make.jl in the 2.0 version. If anyone wants to do this for other systems, please go ahead. We are missing the Boltzmann Wealth and a 2D cellular automaton example.

[Datseris]

@kavir1698 where is the Boltzmann example coming from? is there any wikipedia/scholarpedia page to cite?

[kavir1698]

This is from Mesa package (
https://github.com/projectmesa/mesa/blob/master/examples/boltzmann_wealth_model/Readme.md
):

This model is drawn from econophysics and presents a statistical mechanics
approach to wealth distribution. Some examples of further reading on the
topic can be found at:

Milakovic, M. A Statistical Equilibrium Model of Wealth Distribution.
February, 2001.
https://editorialexpress.com/cgi-bin/conference/download.cgi?db_name=SCE2001&paper_id=214

Dragulescu, A and Yakovenko, V. Statistical Mechanics of Money, Income, and
Wealth: A Short Survey. November, 2002
http://arxiv.org/pdf/cond-mat/0211175v1.pdf

On Sun, Nov 24, 2019, 2:02 PM George Datseris [e-mail]
wrote:

@kavir1698 https://github.com/kavir1698 where is the Boltzmann example
coming from? is there any wikipedia/scholarpedia page to cite?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/JuliaDynamics/Agents.jl/issues/20?email_source=notifications&email_token=AA47OUOLZ3BWAXITTHPRJI3QVJ3NPA5CNFSM4IIN65LKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEFAKXGI#issuecomment-557886361,
or unsubscribe
https://github.com/notifications/unsubscribe-auth/AA47OUPNJOH4LEJYCNVZ53TQVJ3NPANCNFSM4IIN65LA
.