Several changes in the documentation, and the addition of a conda env…

…ironment configuration

docs/source/conf.py

@@ -37,6 +37,7 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
     'sphinx.ext.autosummary',
+    'sphinx.ext.autosectionlabel',
     'numpydoc',
     'nbsphinx'
 ]

docs/source/index.rst

@@ -3,8 +3,28 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-p-winds documentation
-=====================
+p-winds: Documentation
+======================
+
+``p-winds`` is an open-source Python implementation of Parker wind models for
+planetary atmospheres, more specifically their upper atmosphere or corona. The
+code is largely based on the theoretical framework of `Oklopčić & Hirata
+(2018)`_ and `Lampón et al. (2020)`_, which themselves based their work on the
+stellar wind model of `Parker (1958)`_.
+
+.. _Oklopčić & Hirata (2018): https://ui.adsabs.harvard.edu/abs/2018ApJ...855L..11O/abstract
+.. _Lampón et al. (2020): https://ui.adsabs.harvard.edu/abs/2020A%26A...636A..13L/abstract
+.. _Parker (1958): https://ui.adsabs.harvard.edu/abs/1958ApJ...128..664P/abstract
+
+In the current version, the code solves the stead-state ionization distribution
+of hydrogen around the planet based on its physical parameters and the
+high-energy irradiation arriving at the planet.
+
+If you want to use the code without installing it locally, you can always run it
+on the cloud (see `this Google Colaboratory quickstart notebook
+<https://colab.research.google.com/drive/1mTh6_YEgCRl6DAKqnmRp2XMOW8CTCvm7?usp=sharing>`_).
+Otherwise, check out the :ref:`installation` guide, or the :ref:`quickstart`
+Jupyter Notebook.
 
 .. toctree::
    :maxdepth: 2

docs/source/installation.rst

@@ -1,17 +1,39 @@
 Installation
 ============
 
-``p_winds`` requires the packages ``numpy``, ``scipy``, and ``astropy``. Installing ``astroquery`` is also recommended.
+``p-winds`` requires the packages ``numpy``, ``scipy``, and ``astropy`` for
+running its main calculations. Installing ``astroquery`` and ``matplotlib`` is
+also recommended.
+
+The recommended way to install ``p-winds`` and its dependencies is through a
+``conda`` environment and then compiling it from source. Installing it in an
+environment is not strictly necessary (you can just skip to the compiling from
+source if you prefer), but it is a good practice, especially because ``p-winds``
+is currently an alpha release.
 
 First, clone the repository:
 
 .. code-block:: bash
 
    git clone https://github.com/ladsantos/p-winds.git
 
-And then navigate to it, and install it:
+Now create the ``conda`` environment. This command will install all the
+necessary dependencies and useful packages at their most up-to-date versions
+inside the environment ``p_env``. Navigate to the source folder and execute:
 
 .. code-block:: bash
 
    cd p-winds
+   conda env create -f p-winds_environment.yml
+
+Next, activate the ``p_env`` environment:
+
+.. code-block:: bash
+
+   conda activate p_env
+
+Finally, compile ``p-winds`` from source:
+
+.. code-block:: bash
+
    python setup.py install

p-winds_environment.yml

@@ -0,0 +1,21 @@
+name: p_env
+
+channels:
+  - conda-forge
+  - defaults
+
+dependencies:
+  - python=>3.7
+  - numpy=>1.19
+  - scipy>=1.6
+  - matplotlib>=3.3
+  - astropy>=4.2
+  - astroquery>=0.4
+  - pytest>=6.2
+  - sphinx>=3.4
+  - ipykernel
+  - nbsphinx
+  - numpydoc
+  - sphinx_rtd_theme
+  - pip
+  - setuptools