Simplify GitHub hyperlinks for repository locations in docs

doc/source/Installation.rst

@@ -348,7 +348,8 @@ More About Host-Files
 As noted above, we provide support for setting default value for particular machines by providing support for *host-files*\ .
 These files are provided mostly for convenience (and to provide parity with machine files provided by the classic build-system).
 They are most useful on HPC systems that provide multiple compiler toolchains.
-These are the *\*.cmake* files in the **config** directory.
+These are the *\*.cmake* files in the :source:`config` directory.
+
 
 Importantly, the usage of *host-files* is optional (and usually not required).
 They usually aren't needed on local systems (if you find that Grackle won't compile without a host-file, please let us know -- that may indicative of a bug).

doc/source/Interaction.rst

@@ -21,18 +21,18 @@ Example Executables
 -------------------
 
 The grackle source code contains examples for C, C++, and Fortran codes.  
-They are located in the **src/example** directory and provide examples
+They are located in the :source:`src/example` directory and provide examples
 of calling all of grackle's functions.
 
-    * **c_example.c** - C example
+    * :code-example:`c_example.c` - C example
 
-    * **c_local_example.c** - C example using only :ref:`local_functions`
+    * :code-example:`c_local_example.c` - C example using only :ref:`local_functions`
 
-    * **cxx_example.C** - C++ example
+    * :code-example:`cxx_example.C` - C++ example
 
-    * **cxx_omp_example.C** - C++ example using OpenMP
+    * :code-example:`cxx_omp_example.C` - C++ example using OpenMP
 
-    * **fortran_example.F** - Fortran example
+    * :code-example:`fortran_example.F` - Fortran example
 
 The instructions for building and executing the examples vary based on the build-system:
 
@@ -420,7 +420,7 @@ When compiling Grackle
   * with the :ref:`CMake build system <cmake_build>`, you should configure the build by assigning the ``GRACKLE_USE_OPENMP`` cmake-variable a value of ``ON`` (more information about modifying settings in this system are provided :ref:`here <how_to_configure>`)
 
 For an example of how to compile your code with OpenMP, see the
-**cxx_omp_example.C** code example (:ref:`examples`).  Once your code has
+:code-example:`cxx_omp_example.C` code example (:ref:`examples`).  Once your code has
 been compiled with OpenMP enabled, the number of threads used can be controlled
 by setting the :c:data:`omp_nthreads` parameter, stored in the ``grackle_data``
 struct.

doc/source/Python.rst

@@ -178,7 +178,7 @@ If you use ``zsh`` as your shell, you will need quotes around
 Running the Example Scripts
 ---------------------------
 
-A number of example scripts are available in the **src/python/examples**
+A number of example scripts are available in the :source:`src/python/examples`
 directory.  These scripts provide examples of ways that Grackle can be
 used in simplified models, such as solving the temperature evolution of
 a parcel of gas at constant density or in a free-fall model.  Each example
@@ -208,7 +208,7 @@ repository.
 
 .. note::
 
-   `GitHub PR #235 <https://github.com/grackle-project/grackle/pull/235>`__ is a pending pull request that seeks to add functionality to make this work in a regular Pygrackle installation (i.e. a non-'editable' install).
+   :gh-pr:`235` is a pending pull request that seeks to add functionality to make this work in a regular Pygrackle installation (i.e. a non-'editable' install).
 
 Cooling Rate Figure Example
 +++++++++++++++++++++++++++

doc/source/conf.py

@@ -29,7 +29,8 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx_tabs.tabs',
+extensions = ['sphinx.ext.extlinks',
+              'sphinx_tabs.tabs',
               'sphinx_rtd_theme']
 
 # Add any paths that contain templates here, relative to this directory.
@@ -246,3 +247,26 @@
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
+
+
+# Extension Options
+# =================
+
+# sphinx.ext.extlinks
+# -------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html#module-sphinx.ext.extlinks
+
+# This config is a dictionary of external sites, where the key is used as a
+# name of a role and the value is the name of a tuple of strings that serve as
+# templates for an external url and a template for the text that gets used.
+_GITHUB_BASE = 'https://github.com/grackle-project/grackle'
+_SRC_BASE = f'{_GITHUB_BASE}/tree/main'
+extlinks = {
+    'source': (_SRC_BASE + '/%s', '%s'),
+    'code-example' : (_SRC_BASE + '/src/example/%s', '%s'),
+    'gh-issue' : (_GITHUB_BASE + '/issues/%s', 'gh-issue#%s'),
+    'gh-pr' : (_GITHUB_BASE + '/pull/%s', 'gh-pr#%s')
+}
+# for example :code-example-file:`c_local_example.c` should link to the GitHub
+# page for c_local_example.c
+