Fix the documentation generation

Fixes: #537 Signed-off-by: Aurélien Bompard <aurelien@bompard.org>
fedora-infra · Aug 24, 2023 · 6d9ddb4 · 6d9ddb4
1 parent 54d0b35
commit 6d9ddb4
Show file tree

Hide file tree

Showing 7 changed files with 39 additions and 59 deletions.
diff --git a/datagrepper/app.py b/datagrepper/app.py
@@ -190,14 +190,14 @@ def preload_docs(endpoint):
     return api_docs
 
 
-htmldocs = dict.fromkeys(["index", "reference", "widget", "charts"])
+htmldocs = dict.fromkeys(["index", "reference", "widget", "charts", "contributing"])
 for key in htmldocs:
     htmldocs[key] = preload_docs(key)
 
 
-def load_docs(request):
-    URL = app.config.get("DATAGREPPER_BASE_URL", request.url_root)
-    docs = htmldocs[request.endpoint]
+def load_docs(page):
+    URL = app.config.get("DATAGREPPER_BASE_URL", flask.request.url_root)
+    docs = htmldocs[page]
     docs = jinja2.Template(docs).render(URL=URL)
     return markupsafe.Markup(docs)
 
@@ -226,28 +226,10 @@ def count_all_messages():
 @app.route("/")
 def index():
     total = count_all_messages()
-    docs = load_docs(flask.request)
+    docs = load_docs("index")
     return flask.render_template("index.html", docs=docs, total=total)
 
 
-@app.route("/reference/")
-@app.route("/reference")
-def reference():
-    return flask.render_template("index.html", docs=load_docs(flask.request))
-
-
-@app.route("/charts/")
-@app.route("/charts")
-def charts():
-    return flask.render_template("index.html", docs=load_docs(flask.request))
-
-
-@app.route("/widget/")
-@app.route("/widget")
-def widget():
-    return flask.render_template("index.html", docs=load_docs(flask.request))
-
-
 @app.route("/raw", methods=["GET"], strict_slashes=False)
 @app.route("/v2/search", methods=["GET"], strict_slashes=False)
 def raw():
@@ -620,6 +602,13 @@ def messagecount():
     return total
 
 
+@app.route("/<page>/")
+def doc(page):
+    if page not in htmldocs:
+        flask.abort(404)
+    return flask.render_template("index.html", docs=load_docs(page))
+
+
 @app.errorhandler(404)
 def not_found(error):  # TODO test this
     return flask.Response(

diff --git a/datagrepper/docs/charts.rst b/datagrepper/docs/charts.rst
@@ -7,8 +7,8 @@ visualize message history in your blog, website, or application.
 Usage
 -----
 
-You simply include an ``<img>`` tag with the ``src`` pointed at the `charts URL
-<charts/line>`_, like this::
+You simply include an ``<img>`` tag with the ``src`` pointed at the charts URL,
+like this::
 
     <html>
       <body>
@@ -37,14 +37,14 @@ Per User
 
 Using a url like ``charts/line?user=remi`` will give you a chart like this:
 
-.. image:: http://localhost:5000/charts/line?user=remi&height=300&title=Activity%20for%20user%20%22remi%22
+.. image:: line?user=remi&height=300&title=Activity%20for%20user%20%22remi%22
 
 Per Package
 ~~~~~~~~~~~
 
 Or you could produce graphs specific to a package with a url like ``charts/line?package=nethack``:
 
-.. image:: http://localhost:5000/charts/line?package=nethack&height=300&title=Fedora%20activity%20for%20the%20nethack%20package
+.. image:: line?package=nethack&height=300&title=Fedora%20activity%20for%20the%20nethack%20package
 
 Per Category
 ~~~~~~~~~~~~
@@ -54,7 +54,7 @@ displaying the count of messages from a particular subsystem.  For
 instance, the graph at ``charts/line?category=buildsys`` shows the trend
 of activity in the koji build system:
 
-.. image:: http://localhost:5000/charts/line?category=buildsys&height=300&title=Koji
+.. image:: line?category=buildsys&height=300&title=Koji
 
 Combining all that
 ~~~~~~~~~~~~~~~~~~
@@ -64,7 +64,7 @@ types like showing only koji messages for the kernel, dracut, and systemd
 packages with
 ``charts/line?package=kernel&package=dracut&package=systemd&category=buildsys``:
 
-.. image:: http://localhost:5000/charts/line?package=kernel&package=dracut&package=systemd&category=buildsys&height=300&title=Koji
+.. image:: line?package=kernel&package=dracut&package=systemd&category=buildsys&height=300&title=Koji
 
 Chart Types
 -----------
@@ -87,7 +87,7 @@ others.  Choose from any of these:
 
 For example, here is ``charts/bar?category=wiki``:
 
-.. image:: http://localhost:5000/charts/bar?category=wiki&height=300&title=Wiki%20Activity
+.. image:: bar?category=wiki&height=300&title=Wiki%20Activity
 
 Styles
 ------
@@ -113,7 +113,7 @@ The full list is:
 
 Check it out.. here's ``charts/horizontalbar?category=fedoratagger&style=light_solarized``:
 
-.. image:: http://localhost:5000/charts/horizontalbar?category=fedoratagger&height=300&style=light_solarized&title=Fedora%20Tagger
+.. image:: horizontalbar?category=fedoratagger&height=300&style=light_solarized&title=Fedora%20Tagger
 
 Splitting Series
 ----------------
@@ -123,54 +123,54 @@ into independent series.  You can do that with the ``split_on`` parameter.
 
 ``charts/line?package=kernel&package=dracut&package=systemd&split_on=packages``:
 
-.. image:: http://localhost:5000/charts/line?package=kernel&package=dracut&package=systemd&split_on=packages&height=300
+.. image:: line?package=kernel&package=dracut&package=systemd&split_on=packages&height=300
 
 You can also split on multiple kinds of factors at once:
 
-.. image:: http://localhost:5000/charts/line?package=kernel&package=dracut&package=systemd&split_on=packages&category=buildsys&category=git&split_on=categories&height=300
+.. image:: line?package=kernel&package=dracut&package=systemd&split_on=packages&category=buildsys&category=git&split_on=categories&height=300
 
 Other options
 -------------
 
 - ``title``, Set a title on the plot.
 
-.. image:: http://localhost:5000/charts/line?height=300&title=Just%20an%20example%20title
+.. image:: line?height=300&title=Just%20an%20example%20title
 
 - ``N``, (int), the number of data points in the graph (the resolution of
   the x-axis).
 
-.. image:: http://localhost:5000/charts/line?N=3&height=300&title=With%20N=3
+.. image:: line?N=3&height=300&title=With%20N=3
 
 - ``width``, (int), Defaults to ``800``.  Sets the width of the plot in pixels.
 - ``height``, (int), Defaults to ``600``.  Sets the height of the plot in pixels.
 
 - ``interpolation``, (boolean), Defaults to ``None``. You can also pass it
   ``cubic`` or ``quadratic``.
 
-.. image:: http://localhost:5000/charts/line?interpolation=cubic&height=300&title=Cubic%20Interpolation
+.. image:: line?interpolation=cubic&height=300&title=Cubic%20Interpolation
 
 - ``human_readable``, (boolean), Defaults to ``True``.  Converts numbers to
   nicer-to-read numbers.
 
-.. image:: http://localhost:5000/charts/line?human_readable=False&height=300&title=Less%20readable,%20maybe..
+.. image:: line?human_readable=False&height=300&title=Less%20readable,%20maybe..
 
 - ``logarithmic``, (boolean), Defaults to ``False``.  Logarithmically scales
   the y-axis.
 
-.. image:: http://localhost:5000/charts/line?logarithmic=True&height=300&title=Logarithmic
+.. image:: line?logarithmic=True&height=300&title=Logarithmic
 
 - ``show_x_labels``, (boolean), Defaults to ``True``.  Show/hide the x-axis
   labels.
 - ``show_y_labels``, (boolean), Defaults to ``True``.  Show/hide the y-ayis
   labels.
 
-.. image:: http://localhost:5000/charts/line?show_x_labels=False&show_y_labels=False&height=300&title=Sans%20labels
+.. image:: line?show_x_labels=False&show_y_labels=False&height=300&title=Sans%20labels
 
 - ``show_dots``, (boolean), Defaults to ``True``.  Show/hide the datapoints.
 
-.. image:: http://localhost:5000/charts/line?show_dots=False&height=300&title=Hidden%20dots
+.. image:: line?show_dots=False&height=300&title=Hidden%20dots
 
 - ``fill``, (boolean), Defaults to ``False``.  Fill the area under curves in
   line plots.
 
-.. image:: http://localhost:5000/charts/stackedline?fill=True&height=300&title=Area%20under%20the%20curve
+.. image:: stackedline?fill=True&height=300&title=Area%20under%20the%20curve
diff --git a/datagrepper/docs/index.rst b/datagrepper/docs/index.rst
@@ -10,16 +10,6 @@ and puts them in a database. These messages is what datagrepper queries.
 
 Datagrepper is curently running in production at https://apps.fedoraproject.org/datagrepper/
 
-Table of Contents
------------------
-
-.. Contributor Guide
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Contributor Guide
-
-   contributing
 
 Pre-requisites
 --------------

diff --git a/datagrepper/templates/base.html b/datagrepper/templates/base.html
@@ -35,8 +35,8 @@
         <ul class="nav navbar-nav nav-justified nav-underline">
             <li class="nav-item"><a class="nav-link" href="{{ url_for('index') }}">Getting&nbsp;started</a></li>
             <li class="nav-item active"><a class="nav-link" href="{{ url_for('raw') }}?rows_per_page=1">Feed</a></li>
-            <li class="nav-item"><a class="nav-link" href="{{ url_for('reference') }}">Reference</a></li>
-            <li class="nav-item"><a class="nav-link" href="{{ url_for('widget') }}">Embedding</a></li>
+            <li class="nav-item"><a class="nav-link" href="{{ url_for('doc', page='reference') }}">Reference</a></li>
+            <li class="nav-item"><a class="nav-link" href="{{ url_for('doc', page='widget') }}">Embedding</a></li>
             <li class="nav-item"><a class="nav-link" href="https://github.com/fedora-infra/datagrepper">Source</a></li>
             <li class="nav-item"><a class="nav-link" href="https://github.com/fedora-infra/datagrepper/issues">Issues</a></li>
         </ul>

diff --git a/datagrepper/templates/index.html b/datagrepper/templates/index.html
@@ -46,9 +46,9 @@
                         <ul class="nav navbar-nav nav-justified nav-underline">
                             <li{% if request.endpoint == 'index' %} class="active nav-item"{% else %} class="nav-item" {% endif %}><a class="nav-link" href="{{ url_for('index') }}">Getting&nbsp;started</a></li>
                             <li class="nav-item"><a class="nav-link" href="{{ url_for('raw') }}?rows_per_page=1&delta=127800">Feed</a></li>
-                            <!-- <li{% if request.endpoint == 'charts' %} class="active"{% endif %}><a href="{{ url_for('charts') }}">Charts</a></li> -->
-                            <li{% if request.endpoint == 'reference' %} class="active nav-item" {% else %} class="nav-item" {% endif %}><a class="nav-link" href="{{ url_for('reference') }}">Reference</a></li>
-                            <li{% if request.endpoint == 'widget' %} class="active nav-item" {% else %} class="nav-item" {% endif %}><a class="nav-link" href="{{ url_for('widget') }}">Embedding</a></li>
+                            <!-- <li{% if request.endpoint == 'charts' %} class="active"{% endif %}><a href="{{ url_for('doc', page='charts') }}">Charts</a></li> -->
+                            <li{% if request.endpoint == 'reference' %} class="active nav-item" {% else %} class="nav-item" {% endif %}><a class="nav-link" href="{{ url_for('doc', page='reference') }}">Reference</a></li>
+                            <li{% if request.endpoint == 'widget' %} class="active nav-item" {% else %} class="nav-item" {% endif %}><a class="nav-link" href="{{ url_for('doc', page='widget') }}">Embedding</a></li>
                             <li class="nav-item"><a class="nav-link" href="https://github.com/fedora-infra/datagrepper">Source</a></li>
                             <li class="nav-item"><a class="nav-link" href="https://github.com/fedora-infra/datagrepper/issues">Issues</a></li>
                         </ul>

diff --git a/news/537.bug b/news/537.bug
@@ -0,0 +1 @@
+Fix the documentation generation on the front page
diff --git a/tests/test_api.py b/tests/test_api.py
@@ -16,21 +16,21 @@ def setUp(self):
 
     @patch("datagrepper.app.dm.Message.grep", return_value=(0, 0, []))
     def test_reference(self, grep):
-        resp = self.client.get("/reference")
+        resp = self.client.get("/reference/")
         self.assertEqual(resp.status_code, 200)
         response = resp.get_data()
         self.assertIn(b"General API notes", response)
 
     @patch("datagrepper.app.dm.Message.grep", return_value=(0, 0, []))
     def test_charts(self, grep):
-        resp = self.client.get("/charts")
+        resp = self.client.get("/charts/")
         self.assertEqual(resp.status_code, 200)
         response = resp.get_data()
         self.assertIn(b"Charts and Graphs", response)
 
     @patch("datagrepper.app.dm.Message.grep", return_value=(0, 0, []))
     def test_widget(self, grep):
-        resp = self.client.get("/widget")
+        resp = self.client.get("/widget/")
         self.assertEqual(resp.status_code, 200)
         response = resp.get_data()
         self.assertIn(b"Embeddable Widget", response)