Docs improvements (feedback needed!)

[bluescarni]

Our documentation website at https://esa.github.io/pagmo2/ needs some improvements, as recently pointed out in issue reports (#258, #263, #279, etc.) and general chatter on the gitter channel.

The API is fully documented, but we are a bit lacking in tutorials and introductory documentation (especially on the C++ side). The installation docs could also be improved and they are currently outdated (e.g., pagmo now a compiled library, we are lagging behind in the production of pip packages of windows so the documentation is not correct - a decision needs to made there, etc.).

I would encourage the community to list in this report ideas/criticism/complaints about our documentation, so we can bundle up the improvements into a dedicated documentation PR and hopefully improve the situation.

I'll start:

• the C++ API documentation should say which header file I should include to use a specific class, function, etc. I started doing this recently, but this information needs to be added everywhere. This will probably require some reorganization of the existing docs so that entities that live in the same header file are grouped together in the sphinx pages.
• in the installation instructions, we should have a section on how to use the exported Pagmo::pagmo target in other CMake projects (see Installing with IPOPT #291) (done, Initial doc fixes #340).
• the minimum Boost version required is now 1.60 (done, Initial doc fixes #340).
• the pip packages on Windows and Linux are now up to date (see Mingw8 Appveyor Builds #292, Manylinux attempt #293).

[bluescarni]

Quoting @ShavaraniMahdi from #258 (regarding installation in Windows)

I was trying to install Pagmo according to the instructions given in the documentation. I encountered some problems that took me a long time to resolve and I thought it is a good idea to share my experience in order to enrich the documentation for future references.

[mpowelson]

First of all, let me say that this looks great. I have also not looked at the Python tutorials very much since I am using Pagmo via C++. However, it strikes me that most people that come across Pagmo (myself included) find it because they have a specific problem they are looking to solve. To me it seems that it would be useful to expand the C++ tutorials section to step through creating a UDP, solving it, and describing some of the knobs that we can turn to effect the results. It looks like much of this might already be in the Python tutorials.

Additionally, an overview of evolutionary algorithm terminology and concepts (or pointers to some good reference material) would be useful. For example, when we instantiate an archipelago with 16 islands each with 20 individuals, what does that mean? What can we expect increasing one of those to do to performance?

[bluescarni]

@mpowelson yes, fully agreed on the first part. In fact, this sort of step-by-step guide on writing a UDP, starting with something simple and then progressing to a more complicated example, is exactly what I had in mind. We sort of have something like that in Python, but not in a well organised fashion. C++ was a bit left behind in terms of tutorials because of manpower issues, in the belief that a larger fraction of users would benefit from Python docs.

I mostly agree on your second point as well, with the partial caveat that some parts of pagmo (such as, e.g., how to tune an archipelago in which different algorithms collaborate to solve the same problem) delve into research territory. But at least giving comprehensive description of the tools one can use to perform such research is definitely something we need to do.

[darioizzo]

• Uniform the naming style for named function arguments in Python (a vs algo, p vs prob, etc...)

[Sceki]

• Add tbb among third-party dependencies for C++ installation (done, Initial doc fixes #340).

[bluescarni]

• typo "matematical" instead of "mathematical" in the algorithm docs (both C++ and Python) (done, Initial doc fixes #340).

[stabilus]

I actually created another issue on this (sorry, only saw this later).

I would also find step-by-step examples very useful, but would even go one step "dummer" (for people like me...): Why not use a practical (as opposed to mathematical) problem like

temperature forecast from sequential historical data containing time series and many features per data sample (Like temperature, wind speed and direction, humidity, percipitation, etc.)

Then go through the entire building of the model and forecasting (and updating data and retraining).

Would be very helpful. Thanks

[darioizzo]

• integral dimension -> integer dimension. Four instances currently detected, mainly in policy replacement stuff

[darioizzo]

• In the docs of the hypervolume utilities (python, see https://esa.github.io/pagmo2/docs/python/utils/py_hv_utils.html), the ref_point is often described as ref_point (2d array-like object) – the points it should be ref_point (2d array-like object) – the reference point

[juliusroeder]

Hi
is anyone currently working on the docs improvements?
Otherwise I'd like to contribute to the docs.
Specifically I'd like to restructure and extend the current "Writing your first optimisation problem" by including a section on solving the specified problem.

Also are the "tutorial/problem_basic.cpp", "tutorial/problem_basic_gh.cpp" and "tutorial/problem_basic_s.cpp" used anywhere in the docs?

[bluescarni]

@juliusroeder I was working on the tutorials but progress has been slow, any help would be very greatly appreciated.

I wrote the first two parts of the C++ tutorial. My plan for the third part was to give an overview of the use of the population class, and then add a fourth part with an overview of the algorithm class, including a solution example. This would conclude the "basic" tutorial.

But at any rate, if you have a different plan in mind, it would be great to hear about it. How to structure the docs is pretty much a unsolved question at this time.

Those files you mention are not used in the docs. I think we can just remove them once the basic tutorial is in place.

[A5troB0y]

@bluescarni are there any plans to add sample codes or examples like in PyGMO documentation?

[bluescarni]

@A5troB0y yes that would be ideal, but it's largely a question of manpower at this time. One plan would be to provide C++ notebooks using the xeus-cling jupyter frontend and include them in the docs, I am doing this in another project of mine here:

https://bluescarni.github.io/mppp/interactive_notebooks.html