More docs fixes (#813)

* Clearer documentation for existing capacity file

* Documentation for making a new release

Author: tsmbland

docs/developer-guide.rst

@@ -0,0 +1,26 @@
+Developer Guide
+===============
+
+This is a work-in-progress guide for developers.
+
+Making a new release
+--------------------
+
+The process for making a new release of MUSE is simple:
+
+- Check the current version number. The best way to do this is to look at the latest
+  tagged release on `GitHub <https://github.com/EnergySystemsModellingLab/MUSE_OS/releases>`_.
+- Decide on the new version number, incrementing the second
+  digit for major changes (e.g. ``v1.2.5`` -> ``v1.3.0``), or the third digit for minor changes
+  (e.g. ``v1.2.5`` -> ``v1.2.6``). Note the the first digit must NOT be incremented as this
+  is reserved for the `MUSE2 project <https://github.com/EnergySystemsModellingLab/MUSE2>`_.
+- Update the version number and date in ``CITATION.cff``
+- Write a release notes document in ``docs/release-notes/`` for the new version, following the
+  template of previous release notes. Make sure to link this in ``docs/release-notes/index.rst``.
+- On GitHub, go to "Releases" -> "Draft a new release". Create a new tag named after the
+  new version number (e.g. "v1.3.0"), and give the release a matching title.
+  Then click "Publish release".
+- This will automatically trigger a new release on `PyPI <https://pypi.org/project/MUSE-OS/>`_,
+  a new DOI on `Zenodo <https://zenodo.org/records/14832641>`_, and
+  a new documentation build on `ReadTheDocs <https://muse-os.readthedocs.io/en/latest/>`_.
+  Allow some time for these to complete, then check that everything looks correct.

docs/index.rst

@@ -23,6 +23,7 @@ ModUlar energy system Simulation Environment: MUSE
    inputs/index
    user-guide/index
    advanced-guide/index
+   developer-guide
    faq
    api
    release-notes/index

docs/inputs/existing_capacity.rst

@@ -4,12 +4,17 @@
 Existing Capacity
 ==========================
 
-This file provides the installed capacity in base year and the decommissioning
-profile in the future periods for each technology in a sector, in each region.
-
-Each sector should have an existing capacity file, which should follow the structure
-reported in the table below, and be referenced from the TOML settings file using the
-``existing_capacity`` key.
+Each sector must have an existing capacity file, which defines the total capacity of all
+pre-defined assets in that sector. This data must be given in the form of a decommissioning
+profile, which shows how much capacity of each technology exists in each region at the
+start of the simulation, and how it is expected to decline over time as these assets are
+decommissioned. Any assets installed *by MUSE* during the simulation will be added on
+top of this existing capacity.
+
+This file should follow the structure shown in the example table below, and be referenced from
+the TOML settings file using the ``existing_capacity`` key. For example, in this case,
+the file shows that in region1 there is 5 MW of existing residential electric boiler
+capacity in 2010, of which 0.5 MW will remain active in 2020, and none will remain by 2030.
 
 .. csv-table:: Existing capacity of technologies: the residential boiler example
    :header: technology, region, 2010, 2020, 2030, 2040, 2050
@@ -18,10 +23,12 @@ reported in the table below, and be referenced from the TOML settings file using
    resBoilerElectric, region2, 39, 3.5, 1, 0.3, 0
 
 ``technology``
-   represents the technology ID and needs to be consistent across all the data inputs.
+   represents the technology ID, which must match a technology defined in the
+   sector's technodata file.
 
 ``region``
-   represents the region ID and needs to be consistent across all the data inputs.
+   represents the region ID, which must match a region defined in the settings TOML.
 
 Years (one column per year)
-   represent the simulated periods.
+   represent the years in the simulation. The values in these columns represent
+   the total installed capacity of the technology in the given year/region.