search

pybamm-team / PyBaMM

Fast and flexible physics-based battery models in Python
https://www.pybamm.org/
BSD 3-Clause "New" or "Revised" License
922 stars 493 forks source link

Add documentation for example scripts in accordance with `sphinx-gallery` #3197

Open agriyakhetarpal opened 11 months ago

agriyakhetarpal commented 11 months ago

We use sphinx-gallery for rendering thumbnail galleries in the built docs for the Jupyter notebooks, which are in the docs/source/examples/ folder. This issue describes tasks to add the example scripts too with said extension. This will require the following:

Ideally, tasks 2 and 3 can be completed in a single PR that follows the completion of the first task

iapoursanidis commented 10 months ago

@agriyakhetarpal @tinosulzer: I would like to try putting some effort on this Issue.

Task 1 is straightforward, and already done locally on my laptop. For Tasks 2 and 3, I am allowed to use the help of ChatGPT for speeding up the process?

agriyakhetarpal commented 10 months ago

Hi, while the use of language models is not an issue, I wouldn't recommend them for this task; their outputs might put you in a position of debug hell. The documentation for sphinx-gallery and its working details are fairly straightforward

iapoursanidis commented 10 months ago

Thanks for the update! Ok, I will move on as suggested and update you accordingly.

agriyakhetarpal commented 7 months ago

Hello @iapoursanidis, how is this coming along? Is there some progress you wish to share with us?

iapoursanidis commented 7 months ago

Dear Agriya, In October, I started a new job at the major industry in battery production here in Greece. According to my contract, I can't be contributing to any other tasks (paid or unpaid).

I am trying to clarify with the human resources whether and to what extent I can contribute to the PyBaMM project.

I will let you know what the result is.

Merry Christmas and a Happy New Year.

All the best, Ioannis Poursanidis

https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail Virus-free.www.avast.com https://www.avast.com/sig-email?utm_medium=email&utm_source=link&utm_campaign=sig-email&utm_content=webmail <#DAB4FAD8-2DD7-40BB-A1B8-4E2AA1F9FDF2>

On Thu, 14 Dec 2023 at 21:50, Agriya Khetarpal @.***> wrote:

Hello @iapoursanidis https://github.com/iapoursanidis, how is this coming along? Is there some progress you wish to share with us?

— Reply to this email directly, view it on GitHub https://github.com/pybamm-team/PyBaMM/issues/3197#issuecomment-1856485661, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABNX7EFGS7775JHZN4NYP6LYJNKA3AVCNFSM6AAAAAA22K7HGKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQNJWGQ4DKNRWGE . You are receiving this because you were mentioned.Message ID: @.***>

Bashamega commented 2 months ago

I can complete task 1

agriyakhetarpal commented 2 months ago

Hi, @Bashamega, we would prefer that someone takes all four tasks (or at least a significant section out of them) in the same PR. This issue can be time-taking to implement. This is because moving the scripts to docs/source/examples/ (first task) will not serve much use without them being added to the documentation (second task), and therefore the tasks are inherently connected in their proposition.

Bashamega commented 2 months ago

I can try to finish all the tasks in one go

On Tue, May 7, 2024, 15:10 Agriya Khetarpal @.***> wrote:

Hi, @Bashamega https://github.com/Bashamega, we would prefer that someone takes all four tasks (or at least a significant section out of them) in the same PR. This issue can be time-taking to implement. This is because moving the scripts to docs/source/examples/ (first task) will not serve much use without them being added to the documentation (second task), and therefore the tasks are inherently connected in their proposition.

— Reply to this email directly, view it on GitHub https://github.com/pybamm-team/PyBaMM/issues/3197#issuecomment-2098260191, or unsubscribe https://github.com/notifications/unsubscribe-auth/A2MJG2MQS7FOR65XVTJUZATZBDAE7AVCNFSM6AAAAAA22K7HGKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAOJYGI3DAMJZGE . You are receiving this because you were mentioned.Message ID: @.***>

rtimms commented 2 months ago

Is there some way we can achieve this whilst having both scripts and notebooks living in examples/ rather than docs/source/examples/? It's always surprising to me that they live so deep in docs. I'm not sure how people currently access our examples, but it's confusing that they live in two separate places, and you would normally expect to find them directly in example/.

agriyakhetarpal commented 2 months ago

@rtimms, the major issue is that Sphinx does not allow referencing items in toctrees from files external to the top-level directory where conf.py exists. One solution is to copy the scripts and notebooks at the time of the documentation build using a minimal Sphinx extension I can conjure up. Another cool method I've been recently thinking of using is this project: https://pypi.org/project/sphinx-collections/

@Bashamega, sorry, I just saw your response now. I would say that some of the scripts might need some knowledge of battery modelling for comments to be added, but surely not all of them. There are quite many scripts, so doing this can be a bit tedious as well. Please feel free to work on this if you wish to.