Merge pull request #2648 from pybamm-team/markdown-docs

switch some doc files to markdown, add favicon

Author: valentinsulzer

.gitignore

@@ -6,6 +6,7 @@
 *.DS_Store
 *.mat
 *.csv
+*.hidden
 
 # don't ignore important .txt and .csv files
 !requirements*

docs/conf.py

@@ -49,6 +49,7 @@
     "sphinx.ext.napoleon",
     "sphinx_design",
     "sphinx_copybutton",
+    "myst_parser",
 ]
 
 
@@ -99,6 +100,7 @@
 # https://pydata-sphinx-theme.readthedocs.io/en/latest/index.html# for more information)
 # mostly copied from numpy, scipy, pandas
 html_logo = "source/_static/pybamm_logo.png"
+html_favicon = "source/_static/favicon/favicon.png"
 
 html_theme_options = {
     "logo": {

docs/index.rst

@@ -13,7 +13,7 @@ PyBaMM documentation
    :maxdepth: 1
    :hidden:
 
-   source/user_guide/index
+   User Guide <source/user_guide/index>
    source/api/index
 
 **Version**: |version|

docs/requirements.txt

@@ -20,3 +20,4 @@ sphinx>4.0
 pydata-sphinx-theme
 sphinx_design
 sphinx-copybutton
+myst-parser

docs/source/_static/favicon/favicon.png

@@ -1,85 +1,82 @@
-Fundamentals
-============
+# Fundamentals
 
 PyBaMM (Python Battery Mathematical Modelling) is an open-source battery simulation package
 written in Python. Our mission is to accelerate battery modelling research by
-providing open-source tools for multi-institutional, interdisciplinary collaboration. 
+providing open-source tools for multi-institutional, interdisciplinary collaboration.
 Broadly, PyBaMM consists of
 
-#. a framework for writing and solving systems of differential equations,
-#. a library of battery models and parameters, and
-#. specialized tools for simulating battery-specific experiments and visualizing the results.
+1. a framework for writing and solving systems of differential equations,
+2. a library of battery models and parameters, and
+3. specialized tools for simulating battery-specific experiments and visualizing the results.
 
 Together, these enable flexible model definitions and fast battery simulations, allowing users to
 explore the effect of different battery designs and modeling assumptions under a variety of operating scenarios.
 
-.. note::
+> **NOTE**: This user-guide is a work-in-progress, we hope that this brief but incomplete overview will be useful to you.
 
-    This user-guide is a work-in-progress, we hope that this brief but incomplete overview will be useful to you.
+## Core framework
 
-Core framework
-~~~~~~~~~~~~~~
 The core of the framework is a custom computer algebra system to define mathematical equations,
 and a domain specific modeling language to combine these equations into systems of differential equations
 (usually partial differential equations for variables depending on space and time).
-The `expression tree <https://github.com/pybamm-team/PyBaMM/blob/develop/examples/notebooks/expression_tree/expression-tree.ipynb>`_ example gives an introduction to the computer algebra system, and the `Getting Started <https://github.com/pybamm-team/PyBaMM/tree/develop/examples/notebooks/Getting%20Started>`_ tutorials
+The [expression tree](https://github.com/pybamm-team/PyBaMM/blob/develop/examples/notebooks/expression_tree/expression-tree.ipynb) example gives an introduction to the computer algebra system, and the [Getting Started](https://github.com/pybamm-team/PyBaMM/tree/develop/examples/notebooks/Getting%20Started) tutorials
 walk through creating models of increasing complexity.
 
-Once a model has been defined symbolically, PyBaMM solves it using the Method of Lines. First, the equations are discretised in the spatial dimension, using the finite volume method. Then, the resulting system is solved using third-party numerical solvers. Depending on the form of the model, the system can be ordinary differential equations (ODEs) (if only `model.rhs` is defined), or algebraic equations (if only `model.algebraic` is defined), or differential-algebraic equations (DAEs) (if both `model.rhs` and `model.algebraic` are defined). Jupyter notebooks explaining the solvers can be found `here <https://github.com/pybamm-team/PyBaMM/tree/develop/examples/notebooks/solvers>`_.
+Once a model has been defined symbolically, PyBaMM solves it using the Method of Lines. First, the equations are discretised in the spatial dimension, using the finite volume method. Then, the resulting system is solved using third-party numerical solvers. Depending on the form of the model, the system can be ordinary differential equations (ODEs) (if only `model.rhs` is defined), or algebraic equations (if only `model.algebraic` is defined), or differential-algebraic equations (DAEs) (if both `model.rhs` and `model.algebraic` are defined). Jupyter notebooks explaining the solvers can be found [here](https://github.com/pybamm-team/PyBaMM/tree/develop/examples/notebooks/solvers).
+
+## Model and Parameter Library
 
-Model and Parameter Library
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
 PyBaMM contains an extensive library of battery models and parameters.
 The bulk of the library consists of models for lithium-ion, but there are also some other chemistries (lead-acid, lithium metal).
-Models are first divided broadly into common named models of varying complexity, such as the single particle model` (SPM) or Doyle-Fuller-Newman model (DFN).
+Models are first divided broadly into common named models of varying complexity, such as the single particle model (SPM) or Doyle-Fuller-Newman model (DFN).
 Most options can be applied to any model, but some are model-specific (an error will be raised if you attempt to set an option is not compatible with a model).
-See :ref:`base_battery_model` for a list of options.
+See [](base_battery_model) for a list of options.
 
 The parameter library is simply a collection of python files each defining a complete set of parameters
 for a particular battery chemistry, covering all major lithium-ion chemistries (NMC, LFP, NCA, ...).
-External parameter sets can be linked using entry points (see :ref:`parameter_sets`).
-
-Battery-specific tools
-~~~~~~~~~~~~~~~~~~~~~~
-One of PyBaMM's unique features is the ``Experiment`` class, which allows users to define synthetic experiments using simple instructions in English
+External parameter sets can be linked using entry points (see [](parameter_sets)).
 
-.. code-block:: python
+## Battery-specific tools
 
-    pybamm.Experiment(
-        [
-            ("Discharge at C/10 for 10 hours or until 3.3 V",
-            "Rest for 1 hour",
-            "Charge at 1 A until 4.1 V",
-            "Hold at 4.1 V until 50 mA",
-            "Rest for 1 hour")
-        ]
-        * 3,
-    )
+One of PyBaMM's unique features is the `Experiment` class, which allows users to define synthetic experiments using simple instructions in English
 
-The above instruction will conduct a standard discharge / rest / charge / rest cycle three times, with a 10 hour discharge and 1 hour rest at the end of each cycle. 
+```python
+pybamm.Experiment(
+    [
+        ("Discharge at C/10 for 10 hours or until 3.3 V",
+        "Rest for 1 hour",
+        "Charge at 1 A until 4.1 V",
+        "Hold at 4.1 V until 50 mA",
+        "Rest for 1 hour")
+    ]
+    * 3,
+)
+```
 
-The ``Simulation`` class handles simulating an ``Experiment``, as well as calculating additional outputs such as capacity as a function of cycle number. For example, the following code will simulate the experiment above and plot the standard output variables:
+The above instruction will conduct a standard discharge / rest / charge / rest cycle three times, with a 10 hour discharge and 1 hour rest at the end of each cycle.
 
-.. code-block:: python
+The `Simulation` class handles simulating an `Experiment`, as well as calculating additional outputs such as capacity as a function of cycle number. For example, the following code will simulate the experiment above and plot the standard output variables:
 
-    import pybamm
-    import matplotlib.pyplot as plt
+```python
+import pybamm
+import matplotlib.pyplot as plt
 
-    # load model and parameter values
-    model = pybamm.lithium_ion.DFN()
-    sim = pybamm.Simulation(model, experiment=experiment)
-    solution = sim.solve()
-    solution.plot()
+# load model and parameter values
+model = pybamm.lithium_ion.DFN()
+sim = pybamm.Simulation(model, experiment=experiment)
+solution = sim.solve()
+solution.plot()
+```
 
 Finally, PyBaMM provides cusotm visualization tools:
 
-* :ref:`quick_plot`: for easily plotting simulation outputs in a grid, including comparing multiple simulations
-* :ref:`plot_voltage_components`: for plotting the component overpotentials that make up a voltage curve
+- [](quick_plot): for easily plotting simulation outputs in a grid, including comparing multiple simulations
+- [](plot_voltage_components): for plotting the component overpotentials that make up a voltage curve
 
 Users are not limited to these tools and can plot the output of a simulation solution by accessing the underlying numpy array for the solution variables as
 
-.. code-block:: python
-
-    solution["variable name"].data
+```python
+solution["variable name"].data
+```
 
-and using the plotting library of their choice.
+and using the plotting library of their choice.

…source/user_guide/fundamentals/index.rst …/source/user_guide/fundamentals/index.mddocs/source/user_guide/fundamentals/index.rst renamed to docs/source/user_guide/fundamentals/index.md docs/source/user_guide/fundamentals/index.rst renamed to docs/source/user_guide/fundamentals/index.md

@@ -0,0 +1,40 @@
+# Getting Started
+
+The easiest way to use PyBaMM is to run a 1C constant-current discharge with a model of your choice with all the default settings:
+
+```python
+import pybamm
+model = pybamm.lithium_ion.DFN()  # Doyle-Fuller-Newman model
+sim = pybamm.Simulation(model)
+sim.solve([0, 3600])  # solve for 1 hour
+sim.plot()
+```
+
+or simulate an experiment such as a constant-current discharge followed by a constant-current-constant-voltage charge:
+
+```python
+import pybamm
+experiment = pybamm.Experiment(
+    [
+        ("Discharge at C/10 for 10 hours or until 3.3 V",
+        "Rest for 1 hour",
+        "Charge at 1 A until 4.1 V",
+        "Hold at 4.1 V until 50 mA",
+        "Rest for 1 hour")
+    ]
+    * 3,
+)
+model = pybamm.lithium_ion.DFN()
+sim = pybamm.Simulation(model, experiment=experiment, solver=pybamm.CasadiSolver())
+sim.solve()
+sim.plot()
+```
+
+However, much greater customisation is available. It is possible to change the physics, parameter values, geometry, submesh type, number of submesh points, methods for spatial discretisation and solver for integration (see DFN [script](https://github.com/pybamm-team/PyBaMM/blob/develop/examples/scripts/DFN.py) or [notebook](https://github.com/pybamm-team/PyBaMM/blob/develop/examples/notebooks/models/DFN.ipynb)).
+
+For new users we recommend the [Getting Started](https://github.com/pybamm-team/PyBaMM/tree/develop/examples/notebooks/Getting%20Started) guides. These are intended to be very simple step-by-step guides to show the basic functionality of PyBaMM, and can either be downloaded and used locally, or used online through [Google Colab](https://colab.research.google.com/github/pybamm-team/PyBaMM/blob/develop).
+
+Further details can be found in a number of [detailed examples](https://github.com/pybamm-team/PyBaMM/blob/develop/examples/notebooks/README.md), hosted on
+GitHub. In addition, full details of classes and methods can be found in the [](api_docs).
+Additional supporting material can be found
+[here](https://github.com/pybamm-team/pybamm-supporting-material/).

docs/source/user_guide/getting_started.md

@@ -0,0 +1,24 @@
+(user)=
+
+# PyBaMM user guide
+
+This guide is an overview and explains the important features;
+details are found in [](api_docs).
+
+```{toctree}
+---
+caption: Getting started
+maxdepth: 1
+---
+
+installation/index
+getting_started
+```
+
+```{toctree}
+---
+caption: Fundamentals and usage
+maxdepth: 2
+---
+fundamentals/index
+```