[JOSS Review]: Usage example

[CFGrote]

Re JOSS #4509

Tutorial notebook

The documentation at https://pyfpt.readthedocs.io/en/latest/Installing%20and%20First%20Simulation.html sources the User guide notebooks in User guides/. I found no issue going through them.

A minor source of confusion may arise from the additional (redundant?) notebooks in docs/source, which look identical but miss some local dependencies (e.g. the mpl_style.py module). Maybe they can be removed?

[Jacks0nJ]

I agree this could lead to confusion. The reason they are duplicated is the user guides in docs/source are used to generate html pages for the documentation, so the user guides can also be viewed again there. It was easier to simply duplicate them where the ReadTheDocs pages are generated. I'm more than happy to implement a more elegant solution if you have suggestion.

[CFGrote]

Hi @JacksOnJ, I usually solve this kind of issue by symlinking content in docs/source to places where user's are supposed to find them.

maybe that works for you, too?

On Mon, 2022-07-18 at 00:49 -0700, Joe Jackson wrote:

I agree this could lead to confusion. The reason they are duplicated is the user guides in docs/source are used to generate html pages for the documentation, so the user guides can also be viewed again there. It was easier to simply duplicate them where the ReadTheDocs pages are generated. I'm more than happy to implement a more elegant solution if you have suggestion. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.Message ID: @.***>

[Jacks0nJ]

@CFGrote I'll look into it. I'm currently away from my linux machine, but will try to implement it once I'm back.

[Jacks0nJ]

I've used the nbsphinx-link to allow the documentation read directly from the guides folder. It seems wanting to add Jupyter notebooks to the documentation from a guides folder is a common problem!

So the duplication should hopefully be fixed.

[CFGrote]

Perfect!