Move README content to index, repo readme to redirect to pages site

willGraham01 · willGraham01 · commit 4a76da38492f · 2023-08-18T13:45:13.000+01:00
diff --git a/README.md b/README.md
diff --git a/README.rst b/README.rst
@@ -0,0 +1,3 @@
+This is a repository for storing profiling outputs from the TLOmodel, an epidemiology modelling framework for the Thanzi la Onse project.
+
+Please head to the `online documentation <http://github-pages.ucl.ac.uk/TLOmodel-profiling/>` for details about this repository, and to access the results from profiling runs of the `TLO model <https://github.com/UCL/TLOmodel>`.
diff --git a/source/index.rst b/source/index.rst
@@ -3,8 +3,8 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to TLO Model: Profiling, Developer Documentation!
-=========================================================
+Welcome to the TLO Model: Profiling Documentation
+=================================================
 
 .. toctree::
    :maxdepth: 1
@@ -14,6 +14,26 @@ Welcome to TLO Model: Profiling, Developer Documentation!
    run-statistics
    repo-overview
 
+This is a repository for storing profiling outputs from the TLOmodel, an epidemiology modelling framework for the Thanzi la Onse project.
+
+Running Simulations with the Model
+----------------------------------
+
+For more information about setting up, using, and running simulations using the model, `please see the main repository <https://github.com/UCL/TLOmodel>`_ and information provided there.
+
+View the Profiling Results
+--------------------------
+
+Profiling results are hosted on `GitHub pages <http://github-pages.ucl.ac.uk/TLOmodel-profiling>`_ and are built using ``sphinx`` and some custom Python scripts to process the results data.
+
+* :ref:`Lookup table for profiling runs <profiling>`
+* :ref:`Summary page for captured run statistics <run-statistics>`
+
+Developer Documentation
+-----------------------
+
+For developer information about this repository; such as how the repository is organised, how the website is built, and documentation for the functions and scripts, :ref:`please see the online documentation <developers>`.
+
 Indices and tables
 ==================
 
diff --git a/source/profiling.rst b/source/profiling.rst
@@ -1,4 +1,6 @@
 Profiling Runs: Lookup Page
 ===========================
 
+.. _profiling:
+
 <<<MATCH_PATTERN_FOR_MARKDOWN_TABLE_INSERT>>>
diff --git a/source/repo-overview.rst b/source/repo-overview.rst
@@ -1,31 +1,41 @@
-Repository Overview
-===================
+Developer Documentation
+=======================
+
+.. _developers:
 
 The purpose of this repository is to provide a storage space for profiling runs performed on the `Thanzi la Onse model <https://github.com/UCL/TLOmodel>`_, and a convenient way to page through the results that doesn't require developers to download the results for themselves.
 The result is this repository, or specifically `the pages deployment <http://github-pages.ucl.ac.uk/TLOmodel-profiling>`_.
 
 Profiling session outputs, ``.pyisession`` files, are pushed from the `model repository`_ when the profiling workflow has completed to the `source branch`_.
 This triggers the `build-website <https://github.com/UCL/TLOmodel-profiling/blob/main/.github/workflows/build-website.yaml>`_ workflow which will run the `build script`_.
-This script will parse the files on the source branch, as well as update the developer docs with any changes, and deploy the new website over the old one.
+This script will parse the files on the `source branch`_, as well as update the developer docs with any changes, and deploy the new website over the old one.
 
 On PRs, the profiling results HTML and developer docs HTML are required to build successfully before merging, however deployment only takes place when the ``build-website`` workflow is run on ``main``, or triggered as a direct result of new profiling results being pushed.
 
 Build Steps
 -----------
 
-The build steps can be summarised as follows.
+The website consists of two parts:
+* The profiling results and statistics, which are created by the scripts in ``website_build`` and the results stored on the `source branch`_.
+* The developer documentation, which is created from the content of the ``source`` folder.
+
+The website is built using `sphinx <https://www.sphinx-doc.org/en/master/index.html>`_, which is invoked at the end of the ``website_build/build_site.py`` script (specifically within the ``WebsiteBuilder.build()`` method).
+Before ``sphinx-build`` can be invoked however, the profiling results on the `source branch`_ need to be parsed before ``sphinx`` is in a position to publish the website.
+As such, the ``WebsiteBuilder`` first creates a *pre-build* directory, and copies the content of the ``source`` directory into this pre-build directory as a starting point.
+Files are then added to the pre-build directory as needed; these include ``pyinstrumment`` sessions rendered as HTML, and plots for runtime statistics.
+Lookup tables for profiling runs are also generated and their content is inserted into the placeholder locations in the `profiling.rst` and `run-statistics.rst` files in the pre-build directory.
+Having done this pre-build step, ``sphinx`` will be invoked on the pre-build directory to build the HTML content of the website.
 
-* Use `sphinx <https://www.sphinx-doc.org/en/master/index.html>`_ to build the developer docs; documenting the functions, classes, and scripts that perform the heavy lifting.
-* Run the build script to process the profiling results.
-   #. Scan the source branch for all ``pyisession`` files
-   #. Render all profiling output files to HTML
-   #. Process additional statistics that were pushed across with the profiling outputs, and produce plots.
-   #. Write the lookup table, profiling_index.md
-   #. Write the run statistics, run_statistics.md
-   #. Include the index page in the build directory
-* Combine the ``sphinx`` build and profiling results, and deploy to GitHub pages.
+An overview of the steps in the ``build_site.py`` script is provided below:
+#. Copy the ``source`` directory into the pre-build directory.
+#. Scan the source branch for all ``.pyisession`` files
+#. Render all profiling output files to HTML
+#. Process additional statistics that were pushed across with the profiling outputs, and produce plots.
+#. Write the lookup table to ``profiling.rst``.
+#. Write the run statistics to ``run_statistics.rst``.
+#. Invoke ``sphinx-build`` on the pre-build directory to create the website.
 
-The build script makes use of a ``pandas`` DataFrame to keep track of the summary stats and the correspondence between ``.pyisession`` files and HTML outputs, for example.
+The build script makes use of a ``pandas`` DataFrame to keep track of the summary stats and the correspondence between ``.pyisession`` files and HTML outputs.
 
 Contents of the source branch
 -----------------------------
@@ -40,7 +50,7 @@ Files on the source branch as assumed to have filenames in the following style:
 * ``run_number``: The ``github.run_id`` of the workflow that ran.
 * ``commit_sha``: The ``github.sha`` of the commit on which the profiling run was triggered.
 
-In addition to the ``pyisession`` files, additional statistics that cannot be saved by the profiler (like the size of the final simulation population) can also be present on the source branch.
+In addition to the ``.pyisession`` files, additional statistics that cannot be saved by the profiler (like the size of the final simulation population) can also be present on the source branch.
 The additional statistics are assumed to be in ``JSON`` files that carry the same filename as their profiling output counterpart, but with the ``.stats.json`` extension.
 These files are processed by the build script when producing the additional statistics page.
 Additional statistics are not required to be present, as missing entries will be skipped or highlighted when rendering the corresponding page.
diff --git a/source/run-statistics.rst b/source/run-statistics.rst
@@ -1,4 +1,6 @@
 Run Statistics
 ==============
 
+.. _run-statistics:
+
 <<<MATCH_PATTERN_FOR_RUN_STATS_PLOTS>>>
diff --git a/website_build/stat_plots.py b/website_build/stat_plots.py
@@ -61,7 +61,7 @@ def rst_for_run_plots(plot_dict: Dict[str, Path], build_dir: Path) -> List[str]:
     rst_string = ""
     for plot_name, location in plot_dict.items():
         rst_string += f"\n{plot_name}"
-        rst_string += "\n" + ("=" * len(plot_name))
+        rst_string += "\n" + ("-" * len(plot_name))
         rst_string += "\n" * 2
         rst_string += write_rst_image(location, build_dir)
         rst_string += "\n"
diff --git a/website_build/utils.py b/website_build/utils.py
@@ -91,7 +91,7 @@ def write_rst_image(link: Path, relative_to: Path = None) -> str:
         image_source = os.path.relpath(link, relative_to)
     else:
         image_source = str(link)
-    return f"..image:: {image_source}"
+    return f".. image:: {image_source}"
 
 
 def replace_in_file(file: Path, search_for: str, replace_with: str) -> None:

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+This is a repository for storing profiling outputs from the TLOmodel, an epidemiology modelling framework for the Thanzi la Onse project.`
	`2`	`+`
	`3`	+Please head to the `online documentation <http://github-pages.ucl.ac.uk/TLOmodel-profiling/>` for details about this repository, and to access the results from profiling runs of the `TLO model <https://github.com/UCL/TLOmodel>`.