Add .readthedocs.yaml

doc -> docs Minor doc fixes.
lhupfeldt · Oct 24, 2024 · ce6d862 · ce6d862
1 parent a5ecccf
commit ce6d862
Show file tree

Hide file tree

Showing 20 changed files with 54 additions and 21 deletions.
diff --git a/.gitignore b/.gitignore
@@ -18,4 +18,4 @@ build
 test/out
 
 # Sphinx
-doc/_build/*
+docs/_build/*
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,37 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "20"
+    # rust: "1.70"
+    # golang: "1.20"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  # builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#   - pdf
+#   - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
diff --git a/INSTALL.md b/INSTALL.md
@@ -149,5 +149,5 @@ Documentation
 
 2. Build documentation:
 
-        cd doc/source
+        cd docs/source
         make html (or some other format supported by sphinx)
diff --git a/doc/requirements.txt → docs/requirements.txt b/doc/requirements.txt → docs/requirements.txt
diff --git a/doc/source/Makefile → docs/source/Makefile b/doc/source/Makefile → docs/source/Makefile
diff --git a/doc/source/_static/.gitkeep → docs/source/_static/.gitkeep b/doc/source/_static/.gitkeep → docs/source/_static/.gitkeep
diff --git a/doc/source/conf.py → docs/source/conf.py b/doc/source/conf.py → docs/source/conf.py
diff --git a/doc/source/index.rst → docs/source/index.rst b/doc/source/index.rst → docs/source/index.rst
diff --git a/doc/source/jenkinsflow.flow.rst → docs/source/jenkinsflow.flow.rst b/doc/source/jenkinsflow.flow.rst → docs/source/jenkinsflow.flow.rst
diff --git a/doc/source/jenkinsflow.jenkins_api.rst → docs/source/jenkinsflow.jenkins_api.rst b/doc/source/jenkinsflow.jenkins_api.rst → docs/source/jenkinsflow.jenkins_api.rst
diff --git a/doc/source/jenkinsflow.jobload.rst → docs/source/jenkinsflow.jobload.rst b/doc/source/jenkinsflow.jobload.rst → docs/source/jenkinsflow.jobload.rst
diff --git a/doc/source/jenkinsflow.rst → docs/source/jenkinsflow.rst b/doc/source/jenkinsflow.rst → docs/source/jenkinsflow.rst
diff --git a/doc/source/jenkinsflow.script_api.rst → docs/source/jenkinsflow.script_api.rst b/doc/source/jenkinsflow.script_api.rst → docs/source/jenkinsflow.script_api.rst
diff --git a/doc/source/jenkinsflow.unbuffered.rst → docs/source/jenkinsflow.unbuffered.rst b/doc/source/jenkinsflow.unbuffered.rst → docs/source/jenkinsflow.unbuffered.rst
diff --git a/...nkinsflow.utils.set_build_description.rst → ...nkinsflow.utils.set_build_description.rst b/...nkinsflow.utils.set_build_description.rst → ...nkinsflow.utils.set_build_description.rst
diff --git a/noxfile.py b/noxfile.py
@@ -18,7 +18,7 @@
 _HERE = Path(__file__).absolute().parent
 _TEST_DIR = _HERE/"test"
 _DEMO_DIR = _HERE/"demo"
-_DOC_DIR = _HERE/"doc"
+_DOC_DIR = _HERE/"docs"
 
 sys.path.extend((str(_HERE), str(_DEMO_DIR)))
 
@@ -192,7 +192,7 @@ def build(session):
 @nox.session(python=_PY_VERSIONS[0], reuse_venv=True)
 def docs(session):
     session.install("--upgrade", ".", "-r", str(_DOC_DIR/"requirements.txt"))
-    session.run("make", "-C", "doc/source", "html")
+    session.run("make", "-C", "docs/source", "html")
 
 
 @nox.session(python=_PY_VERSIONS[0], reuse_venv=True)

diff --git a/pytest.ini b/pytest.ini
@@ -3,4 +3,4 @@
 [pytest]
 minversion = 7.4.1
 testpaths = test
-norecursedirs = __pycache__ utils perf doc dist demo
+norecursedirs = __pycache__ utils perf docs dist demo
diff --git a/readthedocs-requirements.txt b/readthedocs-requirements.txt
diff --git a/sphinx-bootstrap.sh b/sphinx-bootstrap.sh
@@ -1,4 +1,4 @@
 #!/bin/bash
 
 exclude="test demo ordered_enum.py mocked.py setup.py"
-sphinx-apidoc -f -A "Lars Hupfeldt Nielsen" -V 1.0 -R 1.0.0 --maxdepth 2 --full --separate -o doc/source/ ../jenkinsflow $exclude
+sphinx-apidoc -f -A "Lars Hupfeldt Nielsen" -V 1.0 -R 1.0.0 --maxdepth 2 --full --separate -o docs/source/ ../jenkinsflow $exclude
diff --git a/src/flow.py b/src/flow.py
@@ -117,7 +117,7 @@ def propagate_result(self):
         if self.result in (BuildResult.SUCCESS, BuildResult.SUPERSEDED) or self.propagation == Propagation.UNCHECKED:
             return BuildResult.SUCCESS
         if self.result == BuildResult.UNKNOWN and self.assume_finished_after:
-            return BuildResult.SUCCESS            
+            return BuildResult.SUCCESS
         if self.result == BuildResult.UNSTABLE or self.propagation == Propagation.FAILURE_TO_UNSTABLE:
             return BuildResult.UNSTABLE
         return BuildResult.FAILURE
@@ -555,15 +555,18 @@ def invoke(self, job_name, assume_finished_after: int = 0, **params):
         Args:
             job_name (str): This can take two different formats:
                 For simple jobs: The the name of the job in Jenkins, e.g.: 'aaa'. I.e. NOT 'job/aaa' which is how the URL path appears.
-                  If the surrounding flow sets the :py:obj:`job_name_prefix` the actual name of the invoked job will be the parent flow job_name_prefix + job_name.
+                If the surrounding flow sets the :py:obj:`job_name_prefix` the actual name of the invoked job will be the parent flow job_name_prefix + job_name.
+
                 For GitHub folder jobs: '<github-organization>[/<repository>[/<branch>]]', e.g.: 'aaa/bbb/main', NOT 'job/aaa/job/bbb/job/main' as in URL.
-                  Support for GitHub folder jobs is experimental!
-                  For GitHub folder jobs 'job_name_prefix' is applied to the each part of the name! Probably not useful! Semantics may change!
-                  Note that invoking '<github-organization>[/<repository>]' without <branch> triggers a 'scan'. May change!
+                Support for GitHub folder jobs is experimental!
+                For GitHub folder jobs 'job_name_prefix' is applied to the each part of the name! Probably not useful! Semantics may change!
+                Note that invoking '<github-organization>[/<repository>]' without <branch> triggers a 'scan'. May change!
+
             assume_finished_after:Seconds. If the job has not finished after this amount of time, then assume it is finished and continue.
-                  Note: This is a hack to support organization and repository scan for GitHub folder jobs. There is no way to determine when a scan is finished.
-                  This may change!
-                  If you expect specific jobs or branches after a scan, then you should check for the existence of those or maybe try to build and use the retry feature.
+                Note: This is a hack to support organization and repository scan for GitHub folder jobs. There is no way to determine when a scan is finished.
+                This may change!
+                If you expect specific jobs or branches after a scan, then you should check for the existence of those or maybe try to build and use the retry feature.
+
             **params (str, int, boolean): Arguments passed to Jenkins when invoking the job. Strings are passed as they are,
                 booleans are automatically converted to strings and down-cased, integers are automatically converted to strings.
         """