Make docs more maintainable

[agriyakhetarpal]

Description

1. Adds PyBaMM modules to index.rst using the .. automodule:: directive—the toctrees have been moved to their module-specific __init__.py files. The aim of this PR is to make future updates to toctrees for classes and methods easier

Type of change

Please add a line in the relevant section of CHANGELOG.md to document the change (include PR #) - note reverse order of PR #s. If necessary, also add to the list of breaking changes.

• New feature (non-breaking change which adds functionality)
• Optimization (back-end change that speeds up the code)
• Bug fix (non-breaking change which fixes an issue)

Key checklist:

• No style issues: $ pre-commit run (see CONTRIBUTING.md for how to set this up to run automatically when committing locally, in just two lines of code)
• All tests pass: $ python run-tests.py --all
• The documentation builds: $ python run-tests.py --doctest

You can run unit and doctests together at once, using $ python run-tests.py --quick.

Further checks:

• Code is commented, particularly in hard-to-understand areas
• Tests added that prove fix is effective or that feature works

[codecov]

Codecov Report

Patch coverage has no change and project coverage change: -0.01 ⚠️

Comparison is base (2d2bfc4) 99.71% compared to head (b37b740) 99.71%.

❗ Current head b37b740 differs from pull request most recent head 02cf817. Consider uploading reports for the commit 02cf817 to get more accurate results

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #3066      +/-   ##
===========================================
- Coverage    99.71%   99.71%   -0.01%     
===========================================
  Files          248      248              
  Lines        18749    18738      -11     
===========================================
- Hits         18695    18684      -11     
  Misses          54       54              

Impacted Files	Coverage Δ
pybamm/parameters/__init__.py	100.00% <ø> (ø)

... and 5 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[martinjrobins]

This looks really handy, thanks @agriyakhetarpal

[agriyakhetarpal]

I do have plans to push further changes here and add sphinx.ext.autosummary to generate the pages automatically, but I have not had success locally yet

[Saransh-cpp]

Is this ready for merging?

[agriyakhetarpal]

Yes and no. I had planned to add sphinx.ext.autosummary and tried to do so, but it creates multiple issues with our documentation structure at the moment—to be discussed in our meeting this week. The PR in its current state is ready to merge, however, following a discussion.

[agriyakhetarpal]

Closing this PR in favour of keeping the documentation separate instead of having it in different places, plus the fact that adding sphinx.ext.autosummary brought up more issues with differences in folder structure such as how our API is defined for discretisations and spatial methods, models and submodels, and the expression tree classes and methods—it is possible that this can be revisited during discussions around #2427 and what it entails with our public-private API demarcation.