(docs) compile sphinx docs without errors or warnings [skip ci]

docs/conf.py

@@ -62,7 +62,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/user-guide/setup.rst → docs/developer-guide/setup.rst

@@ -3,7 +3,7 @@ Initial conditions / writing your own setup routine
 
 Steps are:
 
-1. check that a :doc:`setup routine for your problem <setups>` does not already exist.
+1. check that a :doc:`setup routine for your problem </user-guide/setups>` does not already exist.
 2. copy one of the existing setups (e.g. setup_unifdis.f90) to a new
    file (e.g. setup_myproblem.f90).
 3. edit this file.
@@ -64,26 +64,26 @@ be present in the subroutine).
 Utility routines
 ~~~~~~~~~~~~~~~~
 
-There are several routines in the :doc:`libsetup </api/setup>` library to assist with setting up the
+There are several routines in the :doc:`libsetup </api/setup/index>` library to assist with setting up the
 particle positions:
 
-+---------------------------------------+-----------------------------------------------+
-| module/subroutine                     | purpose                                       |
-+=======================================+===============================================+
-| :doc:`set_unifdis <api/set_unifdis>`  | sets up a uniform particle distribution with  |
-|                                       | particles set on various lattice options      |
-+---------------------------------------+-----------------------------------------------+
-| :doc:`set_sphere <api/set_sphere>`    | sets up a uniform density sphere              |
-|                                       | (interface to set_unifdis)                    |
-+---------------------------------------+-----------------------------------------------+
-| :doc:`set_disc <api/set_disc>`        | sets up a single accretion disc with given    |
-|                                       | surface density and temperature profiles      |
-+---------------------------------------+-----------------------------------------------+
-| :doc:`set_binary <api/set_binary>`    | sets up a binary consisting of two point mass |
-|                                       | particles with all 6 orbital elements         |
-+---------------------------------------+-----------------------------------------------+
-| :doc:`set_slab <api/set_slab>`        | sets up a thin slab for 2D tests done in 3D   |
-+---------------------------------------+-----------------------------------------------+
++---------------------------------------------+-----------------------------------------------+
+| module/subroutine                           | purpose                                       |
++=============================================+===============================================+
+| :doc:`set_unifdis </api/setup/set_unifdis>` | sets up a uniform particle distribution with  |
+|                                             | particles set on various lattice options      |
++---------------------------------------------+-----------------------------------------------+
+| :doc:`set_sphere </api/setup/set_sphere>`   | sets up a uniform density sphere              |
+|                                             | (interface to set_unifdis)                    |
++---------------------------------------------+-----------------------------------------------+
+| :doc:`set_disc </api/setup/set_disc>`       | sets up a single accretion disc with given    |
+|                                             | surface density and temperature profiles      |
++---------------------------------------------+-----------------------------------------------+
+| :doc:`set_binary </api/setup/set_binary>`   | sets up a binary consisting of two point mass |
+|                                             | particles with all 6 orbital elements         |
++---------------------------------------------+-----------------------------------------------+
+| :doc:`set_slab </api/setup/set_slab>`       | sets up a thin slab for 2D tests done in 3D   |
++---------------------------------------------+-----------------------------------------------+
 
 Try to use these wherever possible. This makes the setup routines much
 simpler and means less cut-and-pasting between otherwise similar setups.

docs/developer-guide/testing.rst

@@ -106,7 +106,7 @@ The buildbot
 ~~~~~~~~~~~~
 
 The buildbot also runs in `an action <https://github.com/danieljprice/phantom/actions>`_ and checks that the code compiles in :doc:`all of
-the possible SETUP configurations in the Makefile <setups>`. You can run this
+the possible SETUP configurations in the Makefile </user-guide/setups>`. You can run this
 offline as follows::
 
    cd phantom/scripts
@@ -134,8 +134,8 @@ I suggest to do this *only* as a last resort. The recommended steps are as follo
 
 Running the actions locally
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-1. Install `Docker <https://docs.docker.com/desktop/install/mac-install/>`_
-2. Install `act <https://github.com/nektos/act>`_
+1. Install `Docker <https://docs.docker.com/desktop/install/mac-install/>`__
+2. Install `act <https://github.com/nektos/act>`__
 3. run the pull_request workflow
 
 ::
@@ -145,9 +145,9 @@ Running the actions locally
 Checking the phantom build that is failing manually
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 If you just want to check things manually but in the same environment
-as used in the actions, try the following::
+as used in the actions, try the following:
 
-1. Install [Docker](https://docs.docker.com/desktop/install/mac-install/)
+1. Install `Docker <https://docs.docker.com/desktop/install/mac-install/>`__
 2. Install Docker command line tools
 
 ::

docs/examples/CE.rst

@@ -1,5 +1,5 @@
 How to set up and run a common envelope binary simulation
-=========================================================
+==========================================================
 
 Polytropic star + sink companion
 --------------------------------
@@ -76,7 +76,9 @@ Use SETUP=star or SETUP=dustystar and if not specified, the default options.
       the core mass is the same as the one you have measured from MESA (0.46Mo in Jan_Star_Phantom_Profile.data).
       This produces a file called star.setup - this file has all the options so you can edit it.
   2.4 vim  star.setup, (write_rho_to_file = T)
-Relaxation
+
+
+Relaxation of the star
 
 ::
 

docs/examples/binary.rst

@@ -2,11 +2,11 @@ Binary stars and common envelope evolution
 ============================================
 
 Setting up and relaxing binary stars (the easy way)
----------------------------------------------------
-The one-stop-shop to setup a binary star simulation is as follows::
+----------------------------------------------------
+The one-stop-shop to setup a binary star simulation is as follows:
 
 make a new directory and write a local Makefile
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ::
 

docs/examples/disc.rst

@@ -181,9 +181,9 @@ which produces::
   secondary mass          :    1.00
   mass ratio              :    1.00
 
-For a circumprimary disc the equation of state is set to ieos=6, such that the radius is taken with respect to the first sink particle in the simulation. See :doc:`Equations of state available in Phantom <physics/eos>`
+For a circumprimary disc the equation of state is set to ieos=6, such that the radius is taken with respect to the first sink particle in the simulation. See :doc:`Equations of state available in Phantom </physics/eos>`
 
-The Farris et al. (2014) :doc:`equation of state <eos>` (ieos=14 for a binary or ieos=13 if there are more than two stars) is also useful for a flyby simulation if one does not want to have excessively cold material around the secondary
+The Farris et al. (2014) :doc:`equation of state </physics/eos>` (ieos=14 for a binary or ieos=13 if there are more than two stars) is also useful for a flyby simulation if one does not want to have excessively cold material around the secondary
 
 
 Protoplanetary disc with embedded planets

docs/examples/index.rst

@@ -11,10 +11,12 @@ This section contains some examples of physical problems that you can solve with
    disc
    binary
    star
+   CE
    softstar
    dustsettle
    dustgrowth
    density
    hierarchicalsystems
    selfgravity_gravitationalinstability
+   phantomNR
    wind

docs/examples/mdot.rst

@@ -66,7 +66,7 @@ Write an analysis module
 
 More generally, to have full access to all of the sink particle
 information in the dump files, :doc:`write yourself a module for the
-phantomanalysis utility <analysis>`. Then you can just import the sink
+phantomanalysis utility </user-guide/analysis>`. Then you can just import the sink
 particle arrays directly and perform whatever analysis you desire.
 
 You can access the mass accreted by a sink particle by first importing

docs/examples/selfgravity_gravitationalinstability.rst

@@ -1,15 +1,15 @@
 Simulation of self-gravitating and gravitationally unstable accretion discs
-====================================================================
+============================================================================
 
 In PHANTOM, it is possible to perform simulations of accretion discs taking into account the role of the disc self-gravity and, possibly, to trigger gravitational instability. 
 
 Self-gravity in (vertically isothermal) accretion discs
-------------------
+--------------------------------------------------------
 Normally in the *disc* and *dustydisc* environments the disc self-gravity is not taken into account. Indeed, usually the disc to star mass ratio is so low that the disc contribution to the gravitational potential is negligible. 
 The setups *isosgdisc* and *dustyisosgdisc* allow simulating vertically isothermal discs with self-gravity and disc viscosity ($α_{SS}$), and work as the *disc* and *dustydisc* ones. 
 
-Gravitational instability accretion discs
-------------------
+Gravitationally unstable accretion discs
+------------------------------------------
 The environments *sgdisc* and *dustysgdisc* allow the user to simulate a gravitationally unstable accretion disc. Gravitational instability is triggered by cooling, using an adiabatic equation of state and without disc viscosity. Usually, a cooling law it is prescribed, and the simplest one has been proposed by Gammie (2001): the cooling timescale $t_{cool}$ is assumed to be proportional to the dynamical time of the disc $t_{dyn}$ so that $t_{cool} = β t_{dyn}$. 
 
 In the *setup* file there are the disc parameters, and in the *input* file it is possible to prescribe the cooling law. In particular, the variables to pay attention to are:

docs/examples/star.rst

@@ -4,11 +4,11 @@ Setting up stars and tidal disruption events
 Setting up and relaxing a star
 ------------------------------
 
-First, follow the usual procedure for initiating a new simulation with
-phantom. We’ll use the “star” setup, but you can also use the
-“polytrope” or “neutronstar” configurations (the first two use self-gravity
+First, follow the :doc:`usual procedure for initiating a new simulation with
+phantom </getting-started/running-first-calculation>`. We’ll use the “:doc:`star </user-guide/setups>`” setup, but you can also use the
+“:doc:`polytrope </user-guide/setups>`” or “:doc:`neutronstar </user-guide/setups>`” configurations (the first two use self-gravity
 for the star, the last one uses an external potential). For tidal disruption
-events in general relativity use“grtde”. That is:
+events in general relativity use “:doc:`grtde </user-guide/setups>`”. That is:
 
 make a new directory and write a local Makefile
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -121,7 +121,7 @@ check the output
 Putting the star on an orbit for a tidal disruption event
 ---------------------------------------------------------
 
-If you used the “tde” or "grtde" setup then simply compile :doc:`moddump <moddump>`::
+If you used the “tde” or "grtde" setup then simply compile :doc:`moddump </user-guide/moddump>`::
 
    $ make moddump
 
@@ -162,8 +162,8 @@ compile phantommoddump
 ~~~~~~~~~~~~~~~~~~~~~~
 
 The module used to compile this utility is specified using MODFILE= in
-phantom/build/Makefile. The default for the “polytrope” setup is
-currently moddump_spheres.f90::
+`build/Makefile_setups <https://github.com/danieljprice/phantom/blob/master/build/Makefile_setups>`__. 
+The default for the “polytrope” setup is currently moddump_spheres.f90::
 
    MODFILE=moddump_spheres.f90
 
@@ -201,4 +201,4 @@ now implement something decent in src/setup/set_Bfield.f90
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 you can either use the pre-cooked magnetic field setups in this routine,
-or you can just make a new :doc:`moddump <moddump>` module that sets up the magnetic field in a custom way.
+or you can just make a new :doc:`moddump </user-guide/moddump>` module that sets up the magnetic field in a custom way.

docs/examples/wind.rst

@@ -30,8 +30,6 @@ For an isothermal wind, use SETUP=isowind
 At the end of these instructions, a wind.setup and wind.in file are created. Each file contains specific options that are described below.
 Note that you may need to run ``./phantomsetup wind`` a few times to get to the final setting. 
 
-::
-
 Content of the .setup file
 --------------------------
 
@@ -64,9 +62,6 @@ so you only need to provide 2 out of these 3 variables.
 
 - If you provide all the quantites, the radius will be recalculated
 
-::
-
-
 Content of the .in file
 -----------------------
 
@@ -87,67 +82,47 @@ Options controlling particle injection
       iboundary_spheres =           5    ! number of boundary spheres (integer)
          outer_boundary =         50.    ! delete gas particles outside this radius (au)
 
-Here’s a brief description of each of them (remember that technical details can be found in `Siess et al. (2023)`
-
-::
+Here’s a brief description of each of them (remember that technical details can be found in `Siess et al. (2023)`::
 
              sonic_type =           0    ! find transonic solution (1=yes,0=no)
 
 decide whether you set the initial wind velocity (``sonic_type = 0``) or if you let the code find the trans-sonic solution.
-In this latter case, you need a high wind temperature (coronal wind) so the pressure gradient can overcome the stellar gravity.
-
-::
+In this latter case, you need a high wind temperature (coronal wind) so the pressure gradient can overcome the stellar gravity::
 
           wind_velocity =         15.    ! injection wind velocity (km/s, if sonic_type = 0)
 
-set the launching wind velocity (if sonic_type = 0)
-
-::
+set the launching wind velocity (if sonic_type = 0)::
 
      wind_inject_radius =       1.100    ! wind injection radius (au, if 0 take Rstar)
 
-set the distance from the star's center where the wind is launched. If set to zero, the stellar surface is assumed
-
-::
+set the distance from the star's center where the wind is launched. If set to zero, the stellar surface is assumed::
 
          wind_mass_rate =   1.000E-05    ! wind mass loss rate (Msun/yr)
 
-set the mass loss rate
-
-::
+set the mass loss rate::
 
        wind_temperature =       2500.    ! wind temperature at the injection point (K)
 
-set the wind temperature. For trans-sonic solution, this value needs to be high (> 10,000 K)
-
-::
+set the wind temperature. For trans-sonic solution, this value needs to be high (> 10,000 K)::
 
        iwind_resolution =          10    ! if<>0 set number of particles on the sphere, reset particle mass
 
 set the number of particles to be launched and given the mass loss rate determines the particle's mass.
-If set to zero, the particle mass defined in the .setup file is used and the code finds the corresponding number of particles to be launched.
-
-::
+If set to zero, the particle mass defined in the .setup file is used and the code finds the corresponding number of particles to be launched::
 
            nfill_domain =           0    ! number of spheres used to set the background density profile
 
-set a background density profile. This option can limit the effect of boundary conditions. The larger nfill_domain, the bigger the domain
-
-::
+set a background density profile. This option can limit the effect of boundary conditions. The larger nfill_domain, the bigger the domain::
 
      wind_shell_spacing =       1.000    ! desired ratio of sphere spacing to particle spacing
 
 set the resolution of the simulation.
 This parameters gives the ratio between the distance of 2 particles on an ejected sphere and the distance between 2 consecutive spheres.
-Its value should be kept close to unity that
-
-::
+Its value should be kept close to unity that::
 
       iboundary_spheres =           5    ! number of boundary spheres (integer)
 
-set the number of shells that serve as inner boundary condition for the wind
-
-::
+set the number of shells that serve as inner boundary condition for the wind::
 
          outer_boundary =         50.    ! delete gas particles outside this radius (au)
 
@@ -207,22 +182,16 @@ set how radiation pressure is accounted for. The star's effective gravity is giv
               g_\mathrm{eff} = \frac{Gm}{r^2} \times (1-\alpha_\mathrm{rad}-\Gamma)
 
 alpha is an ad-hoc parameter that allows the launching of the wind in case of a cool wind for example when dust is not accounted for.
-Gamma is the Eddington factor that depends on the dust opacity. gamma is therefore <> 0 only when dust is activated (``idust_opacity > 0``)
-
-::
+Gamma is the Eddington factor that depends on the dust opacity. gamma is therefore <> 0 only when dust is activated (``idust_opacity > 0``)::
 
               alpha_rad =       1.000    ! fraction of the gravitational acceleration imparted to the gas
 
-parameter entering in the above equation for the effective gravity
-
-::
+parameter entering in the above equation for the effective gravity::
 
              iget_tdust =           1    ! dust temperature (0:Tdust=Tgas 1:T(r) 2:Flux dilution 3:Lucy 4:MCfost)
 
 defines how the dust temperature is calculated. By default one assumes Tdust = Tgas but other options are availabe as well. 
-Options 1-3 use analytical prescriptions, and option 4 uses full 3D RT using the MCfost code (under development!)
-
-::
+Options 1-3 use analytical prescriptions, and option 4 uses full 3D RT using the MCfost code (under development!)::
 
         iray_resolution =          -1    ! set the number of rays to 12*4**iray_resolution (deactivated if <0)
 

docs/getting-started/flatiron.rst

@@ -204,8 +204,8 @@ read the `splash userguide <https://splash-viz.readthedocs.org>`__ for more
 more interesting examples
 -------------------------
 To proceed to a more interesting calculation, just change the name of the :doc:`SETUP
-parameter <setups>` when you created the Makefile in the run directory, as per
-the :doc:`examples <examples>`::
+parameter </user-guide/setups>` when you created the Makefile in the run directory, as per
+the :doc:`examples </examples/index>`::
 
   cd ~/ceph
   mkdir disc