1879461: Runtime errors when building documentation (#105)

* 1879461: Python runtime error when building documentation
This commit updates the Sphinx config file, fixing runtime errors, and adds proper configuration for ReadTheDocs.

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644 (file)
index 0000000..7eada0d
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,12 @@
+version: 2
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "3.10"
+  apt_packages:
+    - libfile-copy-recursive-perl
+  jobs:
+    post_build:
+      - perl docs/makedocs.pl --pod-only
+      - cp -rp docs/en/html/integrating/api/ "$READTHEDOCS_OUTPUT/html/integrating/api"
+      - cp -p docs/en/html/style.css "$READTHEDOCS_OUTPUT/html/"

diff --git a/docs/en/rst/conf.py b/docs/en/rst/conf.py
index dde6787071e7a66a69bd5ce8ab430578197ac67b..075f13ace227a8351678c96e023df2cf93be25dd 100644 (file)
--- a/docs/en/rst/conf.py
+++ b/docs/en/rst/conf.py
@@ -43,17 +43,28 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'BMO'
-copyright = u'2015, The BMO Team'
+project = u'Bugzilla'
+copyright = u'2024, The Bugzilla Team'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '4.2'
+version = 'Unknown'
 # The full version, including alpha/beta/rc tags.
-release = ''
+release = 'Harmony'
+
+for line in open("../../../Bugzilla/Constants.pm"):
+    match = re.search(r'BUGZILLA_VERSION\s+=>\s+"([^"]+)"', line)
+    if (match):
+        release = match.group(1)
+        match = re.search(r'^\d+\.\d+', release)
+        if (match):
+            version = match.group(0)
+        else:
+            version = release
+        break
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -102,7 +113,7 @@ rst_prolog = """
 .. role:: field
     :class: field
 
-.. |min-perl-ver| replace:: 5.10.1
+.. |min-perl-ver| replace:: 5.14.0
 """
 
 rst_epilog = """
@@ -138,7 +149,7 @@ html_style = "bugzilla.css"
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = ""
+html_logo = "../images/bugzlla.png"
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -241,8 +252,8 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'bugzilla', u'BMO Documentation',
-     [u'The BMO Team'], 1)
+    ('index', 'bugzilla', u'Bugzilla Documentation',
+     [u'The The Bugzilla Team'], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -255,8 +266,8 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'BMO', u'BMO Documentation',
-   u'The BMO Team', 'BMO', 'One line description of project.',
+  ('index', 'Bugzilla', u'Bugzilla Documentation',
+   u'The Bugzilla Team', 'Bugzilla', 'One line description of project.',
    'Miscellaneous'),
 ]
 
@@ -286,7 +297,7 @@ texinfo_documents = [
 # regardless of the global pdf_compressed setting.
 
 pdf_documents = [
-('index', u'BMO', u'BMO Documentation', u'The BMO Team'),
+('index', u'Bugzilla', u'Bugzilla Documentation', u'The Bugzilla Team'),
 ]
 
 # A comma-separated list of custom stylesheets. Example:
@@ -372,4 +383,10 @@ pdf_fit_background_mode = 'scale'
 # Temporary highlighting of TODO items
 todo_include_todos = False
 
-extlinks = {'bug': ('https://bugzilla.mozilla.org/show_bug.cgi?id=%s', 'bug  ')}
+# Originally, the readthedocs.org website could not access POD,
+# so we would conditionally override that here if we were building
+# on RTD, but that's no longer the case.
+base_api_url = '../integrating/api/'
+
+extlinks = {'bug': ('https://bugzilla.mozilla.org/show_bug.cgi?id=%s', 'bug  %s'),
+            'api': (base_api_url + '%s', "%s")}

diff --git a/docs/en/rst/index.rst b/docs/en/rst/index.rst
index 73f2487b6c08752c8ac9c2311168cf634c2407e2..f949123d67a65a69e3595ad7bed9eeb51af5ca85 100644 (file)
--- a/docs/en/rst/index.rst
+++ b/docs/en/rst/index.rst
@@ -1,5 +1,5 @@
 ========================================
-BMO Documentation (bugzilla.mozilla.org)
+Bugzilla Documentation (bugzilla.org)
 ========================================
 
 .. toctree::