Docs overhaul2 (#910)

* checkpoint

* docsOverhaul2: complete work

* amend

* more updates

* sphinx-build: imporve to generate preview as well

* ci: fix naming

* allow-deployments from forks

* ci: fix back

Author: clintonsteiner

.github/workflows/build-docs.yml

@@ -2,6 +2,8 @@ name: Sphinx build
 
 on:  # yamllint disable-line rule:truthy
   push:
+    branches:
+      - master
   workflow_dispatch:
 
 jobs:
@@ -29,9 +31,11 @@ jobs:
           name: html-docs
           path: ./doc/html/
 
-      - name: Deploy
+      - name: Deploy Master Docs to GitHub Pages
         if: ${{ github.ref == 'refs/heads/master' }}
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./doc/html
+          publish_branch: gh-pages
+          keep_files: false

.github/workflows/python-package.yml

@@ -16,7 +16,6 @@ concurrency:
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false

README.rst

@@ -1,4 +1,4 @@
-jenkinsapi
+Jenkinsapi
 ==========
 
 .. image:: https://badge.fury.io/py/jenkinsapi.png
@@ -62,14 +62,6 @@ Most users can do the following:
 
 	pip install jenkinsapi
 
-Or:
-
-.. code-block:: bash
-
-	easy_install jenkinsapi
-
-Both of these techniques can be combined with virtualenv to create an application-specific installation.
-
 Using your operating-system's package manager
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -105,7 +97,7 @@ the testsuite with the following command:
 
 .. code-block:: bash
 
-    uv python sync
+    uv sync
     uv run pytest -sv --cov=jenkinsapi --cov-report=term-missing --cov-report=xml jenkinsapi_tests
 
 Otherwise using a virtualenv is recommended. Setuptools will automatically fetch

doc/CONTRIBUTING.md

@@ -6,7 +6,7 @@ The JenkinsAPI project welcomes contributions via GitHub. Please bear in mind th
 Python compatibility
 --------------------
 
-The project currently targets Python 3.8+. Last version compatible with Python 2.7 is tagged as Py2.
+The project currently targets Python 3.8+.
 
 Code formatting
 ---------------

doc/conf.py

@@ -12,10 +12,9 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 import logging
-import importlib.metadata
 import jenkinsapi
 
-VERSION = RELEASE = importlib.metadata.version("jenkinsapi")
+VERSION = RELEASE = jenkinsapi.__version__
 
 if __name__ == "__main__":
     logging.basicConfig()

doc/index.rst

@@ -20,12 +20,12 @@ Sections
 ========
 .. toctree::
    :maxdepth: 2
+   :titlesonly:
 
-   api
-   artifact
-   build
+   readme_link
    using_jenkinsapi
    jenkinsapi
+   submodules/submodule
    ../CONTRIBUTING
 
 Important Links
@@ -60,24 +60,22 @@ Most users can do the following:
 Examples
 --------
 
-JenkinsAPI is intended to map the objects in Jenkins (e.g. Builds, Views, Jobs) into easily managed Python objects::
-
-    Python 2.7.4 (default, Apr 19 2013, 18:28:01)
-    [GCC 4.7.3] on linux2
-    Type "help", "copyright", "credits" or "license" for more information.
-    >>> import jenkinsapi
-    >>> from jenkinsapi.jenkins import Jenkins
-    >>> J = Jenkins('http://localhost:8080')
-    >>> J.keys() # Jenkins objects appear to be dict-like, mapping keys (job-names) to
-    ['foo', 'test_jenkinsapi']
-    >>> J['test_jenkinsapi']
-    <jenkinsapi.job.Job test_jenkinsapi>
-    >>> J['test_jenkinsapi'].get_last_good_build()
-    <jenkinsapi.build.Build test_jenkinsapi #77>
+JenkinsAPI is intended to map the objects in Jenkins (e.g. Builds, Views, Jobs) into easily managed Python objects
+
+.. code-block:: python
+
+   import jenkinsapi
+   from jenkinsapi.jenkins import Jenkins
+   J = Jenkins('http://localhost:8080')
+   J.keys() # Jenkins objects appear to be dict-like, mapping keys (job-names) to ['foo', 'test_jenkinsapi']
+   J['test_jenkinsapi'] # <jenkinsapi.job.Job test_jenkinsapi>
+   J['test_jenkinsapi'].get_last_good_build() # <jenkinsapi.build.Build test_jenkinsapi #77>
 
 JenkinsAPI lets you query the state of a running Jenkins server. It also allows you to change configuration and automate minor tasks on nodes and jobs.
 
-You can use Jenkins to get information about recently completed builds. For example, you can get the revision number of the last successful build in order to trigger some kind of release process.::
+You can use Jenkins to get information about recently completed builds. For example, you can get the revision number of the last successful build in order to trigger some kind of release process.
+
+.. code-block:: python
 
     from jenkinsapi.jenkins import Jenkins
 
@@ -100,19 +98,19 @@ Tips & Tricks
 Getting the installed version of JenkinsAPI
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This package supports PEP-396 by implementing a __version__ attribute. This contains a string in the format x.y.z:
+This package supports PEP-396 by implementing a version attribute. This contains a string in the format x.y.z:
+
+.. code-block:: python
+
+    import jenkinsapi
+    print(jenkinsapi.__version__)
 
-	>>> import jenkinsapi
-    >>> import importlib.metadata
-    >>> print(importlib.metadata.version("jenkinsapi"))
-	0.2.23
 
-There is also a command-line tool for use in the shell:
 
 .. code-block:: bash
 
-    $ jenkinsapi_version
-    0.2.23
+    jenkinsapi_version
+
 
 Project Authors
 ===============
@@ -132,10 +130,12 @@ JenkinsAPI is a pure-Python project and can be improved with almost any programm
 
  * Make sure that pip and uv are installed on your computer. On most Linux systems these can be installed directly by the OS package-manager.
 
- * Change to the new directory and check out the project code into the **src** subdirectory::
+ * Change to the new directory and check out the project code into the **src** subdirectory
+
+.. code-block:: bash
 
- 	cd jenkinsapi
- 	git clone https://github.com/pycontribs/jenkinsapi.git src
+    cd jenkinsapi
+    git clone https://github.com/pycontribs/jenkinsapi.git src
 
  * Install python dependencies and test the project