Change landing page to be profiling-results (#16)

willGraham01 · web-flow · commit f038165f0fae · 2024-05-22T13:53:10.000+01:00
* Force index to redirect to profiling page

* Fix API typo

* Sort profiling results by newest first, and allow clickable commit shas

* Insert profiling lookup directly into index page

* Write lookup table and plots to hidden rst files that are then included

* Apply suggestions from code review
diff --git a/source/conf.py b/source/conf.py
@@ -43,7 +43,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ["_.*rst"]
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -52,6 +52,7 @@
 # a list of builtin themes.
 #
 html_theme = "alabaster"
+master_doc = "documentation"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
diff --git a/source/developers.rst b/source/developers.rst
@@ -27,7 +27,7 @@ The build can be triggered by passing the ``website_builder/builder.py`` script
 
 .. code-block:: bash
 
-   python website_builder/builder.py
+   python website_builder/builder.py <results-branch>
 
 You may pass the ``-h`` or ``--help`` flags for the command line help, which provides a few convenience wrappers for the :class:`builder.Builder` class that manages the website build.
 Configuration options include specifying a particular directory to place the built website into, forcing the removal of any previously (failed or completed) builds, and toggling the structure of static HTML files from profiling outputs into a flat directory or nested directory structure.
diff --git a/source/documentation.rst b/source/documentation.rst
@@ -0,0 +1,47 @@
+.. TLO Model: Profiling documentation master file, created by
+   sphinx-quickstart on Thu Aug 17 13:46:22 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to the TLO Model: Profiling Documentation
+=================================================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   index
+   run-statistics
+   developers
+   api-reference
+
+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.
+
+* :doc:`Lookup table for profiling runs <index>`
+* :doc:`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, :doc:`please see the online documentation <developers>`.
+
+API Reference
+-------------
+
+For details and usage examples of the code in this repository, please see the :doc:`API reference <api-reference>` page.
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
diff --git a/source/index.rst b/source/index.rst
@@ -1,47 +1,6 @@
-.. TLO Model: Profiling documentation master file, created by
-   sphinx-quickstart on Thu Aug 17 13:46:22 2023.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+Profiling Runs: Lookup Page
+===========================
 
-Welcome to the TLO Model: Profiling Documentation
-=================================================
+Profiling results are listed from newest to oldest, based on the timestamp recorded when the profiling run was *triggered*.
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Contents:
-
-   profiling
-   run-statistics
-   developers
-   api-reference
-
-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.
-
-* :doc:`Lookup table for profiling runs <profiling>`
-* :doc:`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, :doc:`please see the online documentation <developers>`.
-
-API Reference
--------------
-
-For details and usage examples of the code in this repository, please see the :doc:`API reference <api-reference>` page.
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`search`
+.. include:: _profiling_table.rst
diff --git a/source/profiling.rst b/source/profiling.rst
diff --git a/source/run-statistics.rst b/source/run-statistics.rst
@@ -1,4 +1,4 @@
 Run Statistics
 ==============
 
-<<<MATCH_PATTERN_FOR_RUN_STATS_PLOTS>>>
+.. include:: _stats_plots.rst
diff --git a/website_builder/builder.py b/website_builder/builder.py
@@ -15,7 +15,6 @@
 from profiling_statistics import STATS
 from utils import (
     md_title_format,
-    replace_in_file,
     rst_title_format,
     safe_remove_dir,
     write_image_link,
@@ -26,12 +25,6 @@
     "Build the website deployment for the profiling results, "
     "placing the resulting files in the build directory."
 )
-# This pattern, where it appears in the template files,
-# will be replaced with the profiling runs lookup table.
-PROFILING_TABLE_MATCH_STRING = "<<<MATCH_PATTERN_FOR_MARKDOWN_TABLE_INSERT>>>"
-# This pattern, where it appears in the template files,
-# will be replaced with the plots for statistics that are tracked across runs
-RUN_PLOTS_MATCH_STRING = "<<<MATCH_PATTERN_FOR_RUN_STATS_PLOTS>>>"
 
 # These columns need to be computed from the statistics that are read in
 # from the statistics files on the source branch
@@ -52,7 +45,7 @@
 class Builder:
     """
     Handles the construction of the gh-pages website, as per the process detailed
-    in http://github-pages.ucl.ac.uk/TLOmodel-profiling/index.html.
+    in http://github-pages.ucl.ac.uk/TLOmodel-profiling.
 
     Build options are configured on initialisation of a class instance;
     members with default values can be passed as keyword arguments to the
@@ -122,22 +115,17 @@ def static_folder(self) -> Path:
     @property
     def profiling_table_file(self) -> Path:
         """
-        The file containing the
-        <<<MATCH_PATTERN_FOR_MARKDOWN_TABLE_INSERT>>>,
-
-        which is where the profiling results lookup table will be inserted.
+        The file into which the profiling results lookup table
+        will be inserted.
         """
-        return self.staging_dir / "profiling.rst"
+        return self.staging_dir / "_profiling_table.rst"
 
     @property
     def statistics_plots_file(self) -> Path:
         """
-        The file containing the
-        <<<MATCH_PATTERN_FOR_RUN_STATS_PLOTS>>>,
-
-        which is where the run statistics plots will be inserted.
+        The file into which the run statistics plots will be inserted.
         """
-        return self.staging_dir / "run-statistics.rst"
+        return self.staging_dir / "_stats_plots.rst"
 
     @property
     def plot_folder(self) -> Path:
@@ -298,7 +286,7 @@ def format_as_title(self, text: str) -> str:
         """
         title_writer: Callable[[str], str]
         if self.website_plaintext_format == "rst":
-            title_writer = lambda t: rst_title_format(t, "-")
+            title_writer = rst_title_format
         elif format == "md":
             title_writer = md_title_format
         return title_writer(text)
@@ -355,14 +343,19 @@ def parse_stats_files_to_df(self) -> None:
         # Can probably do this with .apply() - revisit
         for index, row in self.df.iterrows():
             stats_file = row["stats_file"]
-            self.df.loc[
-                index, STATS.values("dataframe_col_name")
-            ] = STATS.read_from_file(file=stats_file, branch=self.source_branch)
+            self.df.loc[index, STATS.values("dataframe_col_name")] = (
+                STATS.read_from_file(file=stats_file, branch=self.source_branch)
+            )
 
         # Set the commit field from the sha field
-        self.df["Commit"] = self.df["sha"].apply(
-            lambda sha: REPO.git.rev_parse("--short", sha)
-        )
+        def sha_to_clickable(sha: str) -> str:
+            """ """
+            short_sha = REPO.git.rev_parse("--short", sha)
+            site = "https://github.com/UCL/TLOmodel/commit/"
+            as_link = write_page_link(site + sha, link_text=short_sha)
+            return as_link
+
+        self.df["Commit"] = self.df["sha"].apply(sha_to_clickable)
 
         return
 
@@ -372,17 +365,17 @@ def write_profiling_lookup_table(self) -> str:
         by extracting the relevant columns from the DataFrame.
         """
         if self.website_plaintext_format == "rst":
-            lookup_table = self.df[self.cols_for_lookup_table].to_markdown(
-                index=False, tablefmt="grid"
+            lookup_table = (
+                self.df[self.cols_for_lookup_table]
+                .iloc[::-1]
+                .to_markdown(index=False, tablefmt="grid")
             )
         else:
             lookup_table = self.df[self.cols_for_lookup_table].to_markdown(index=False)
 
-        # Write the lookup page into the templated file.
-        replace_in_file(
-            self.profiling_table_file, PROFILING_TABLE_MATCH_STRING, lookup_table
-        )
-
+        # Write table to the corresponding file
+        with open(self.profiling_table_file, "w") as f:
+            f.write(lookup_table)
         return
 
     def write_run_stats_page(self) -> None:
@@ -400,11 +393,9 @@ def write_run_stats_page(self) -> None:
             )
             stat_page_text += "\n"
 
-        # Inject the text into the statistics plot webpage file
-        replace_in_file(
-            self.statistics_plots_file, RUN_PLOTS_MATCH_STRING, stat_page_text
-        )
-
+        # Write plots to the corresponding file
+        with open(self.statistics_plots_file, "w") as f:
+            f.write(stat_page_text)
         return
 
 
diff --git a/website_builder/utils.py b/website_builder/utils.py
@@ -131,7 +131,7 @@ def write_page_link(
     elif relative_to is not None:
         hyperlink = os.path.relpath(link, relative_to)
     else:
-        hyperlink = str(hyperlink)
+        hyperlink = str(link)
     if format == "rst":
         return f"`{link_text} <{hyperlink}>`__"
     elif format == "md":
