[JOSS]: More prose & clearer examples in online docs

[dfm]

I'm reviewing the JOSS submission at openjournals/joss-reviews#41 and most things are looking good, but I'll open a few issues here.

To be consistent with the JOSS requirements, the docs are going to need some work. At the moment, the documentation has a brief statement of need, a single example, and then API docs. More discussion should be included on the readthedocs page to make it easier to get started. This should include things like one or two tutorials (the examples directory is not sufficient - these examples don't even include any comments!), a page outlining the installation procedure, and a more detailed description of the available options.

Another thing that might be good to include is a comparison to some of the other existing Bayesian optimization packages that are already available in Python: fmfn/BayesianOptimization, GPyOpt, and skopt to name a few.

[josejimenezluna]

Hi @dfm

Thanks for your useful comments. Several improvements have been made:

• Two jupyter notebooks have been included in the new tutorials folder to help new users get started.
• All scripts in the examples folder have been briefly commented.
• Extended statement of need in the landing RTD page, and simple installation instructions.
• Features page added to the RTD docs.
• A comparison table with other python packages has also been included in the RTD around.
• All dependencies are now taken care for in the requirements file, so installation is as easy as pip install pyGPGO

Let me know if something else needs to be addressed.

[dfm]

This looks great! Two comments:

1. Can you make the documentation URL more obvious on github? You can add it to the header by clicking on the edit button like the one in the image below (that's one of my repos because I don't get the edit button for your repos :wink:). And I would also make it more prominent in the README.

2. Most of the internal reference links are broken in your docs right now. Check the syntax and use something like :class:`pyGPGO.surrogates.GaussianProcess ` instead of the <pyGPGO.surrogates.GaussianProcess> that you're using now (e.g. http://pygpgo.readthedocs.io/en/latest/features.html#surrogate-models-pygpgo-surrogates)

[josejimenezluna]

Hi @dfm !

• Link to the documentation is now more visible in the repository, both in the header and in the README.md file.

• Internal documentation links are now fixed. Thanks for noticing.

Let me know again if further changes are required.

[dfm]

Looks great! One last issue with the links. I think that you're still using the markdown style for citations, but it would be good to switch to the correct RST syntax: http://docutils.sourceforge.net/docs/user/rst/quickref.html#citations

[josejimenezluna]

Thanks for noticing. The correct RST citation syntax is used in the docs.

[josejimenezluna]

Hi @dfm!

Is there something else that needs to be addressed or can I close this? :)

[dfm]

Oops. Nope. Looks good now!