ci: updated build to work with most recent pdoc version

Documentation updated so that it builds properly with most recent pdoc version.

Alterations made:
- Links now work
- codeblocks updated
- full documentation now renders

Signed-off-by: Jasper Berton <[email protected]>

Author: JasperB-TeamBlue

Diff for: .github/workflows/build.yaml

@@ -21,6 +21,7 @@ jobs:
           - name: centos-stream-9
             shortcut: c9s
             container-name: el9stream
+            pip-command: pip3
 
     name: ${{ matrix.name }}
 
@@ -86,15 +87,15 @@ jobs:
           ref: 'gh-pages'
 
   generate_documentation:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
     steps:
       - name: Install Dependencies
       # This step installs dependencies for python-sdk and pdoc
         run: |
           sudo apt update &&
           sudo apt install -y git \
-            python2 \
-            python2-dev \
+            python3 \
+            python3-dev \
             curl \
             asciidoctor \
             gcc \
@@ -109,34 +110,26 @@ jobs:
       - name: Checkout sources
         uses: actions/checkout@v4
 
-      - name: Install pip2.7
-        # This step installs pip2.7, which will be needed later
-        run: |
-          curl https://bootstrap.pypa.io/pip/2.7/get-pip.py --output get-pip.py
-          python2 get-pip.py
-
-      - name: Install Python-SDK with Python 2.7
+      - name: Install Python-SDK with Python 3
         # This step installs the python-sdk with python2.7, as the extension of pdoc,
         # which is subsequently installed, doesn't have python3 support.
         run: |
-          pip2.7 install setuptools
+          pip install setuptools
           bash .automation/generate-setup-files.sh
-          python2.7 setup.py install --user --prefix=
+          python3 setup.py install --user --prefix=
         shell: bash
 
       - name: Install Pdoc
         # This steps installs an extension of pdoc which supports asciidoc
         # (this extension runs on python2).
         run: |
-          git clone https://github.com/machacekondra/pdoc
-          cd pdoc
-          pip2.7 install -U .
+          pip install pdoc
 
       - name: Install pygments
-        run: pip2.7 install pygments
+        run: pip install pygments
 
       - name: Generate documentation
-        run: pdoc ovirtsdk4 --html --html-dir=html
+        run: pdoc ovirtsdk4 -o ./${{ env.GEN_DOC_DIR }} -t pdoc
 
       - name: Upload generated documentation artifacts
         uses: actions/upload-artifact@v4
@@ -157,7 +150,7 @@ jobs:
         uses: actions/download-artifact@v4
         with:
           name: generated-documentation
-          path: ${{ env.GEN_DOC_DIR }}
+          path: ${{ env.GEN_DOC_DIR }}/
 
       - name: Install package dependencies
         run: |
@@ -197,8 +190,8 @@ jobs:
 
       - name: Move created documentation to gh-pages
         run: |
-          mkdir -p ./ovirt-engine-sdk/${{env.FOLDER}}/
-          cp ./html/ovirtsdk4/* ./ovirt-engine-sdk/${{env.FOLDER}}/
+          mkdir -p ./ovirt-engine-sdk/${{ env.FOLDER }}/
+          cp -r ./${{ env.GEN_DOC_DIR }}/* ./ovirt-engine-sdk/${{ env.FOLDER }}/
 
       - name: Push changes to gh-pages
         run: |

Diff for: lib/ovirtsdk4/__init__.py

@@ -31,9 +31,11 @@
     from urllib import urlencode
     from urlparse import urlparse
 
-from ovirtsdk4 import version
 from ovirtsdk4.http import Response
 
+def get_version():
+    from ovirtsdk4 import version
+    return version.VERSION
 
 class Error(Exception):
     """
@@ -44,20 +46,22 @@ class Error(Exception):
     def __init__(self, message, code=None, fault=None):
         """
         Creates an instance of Error class.
-
-        `message`:: The exception message.
-
-        `code`:: An error code associated to the error. For HTTP related
-        errors, this will be the HTTP response code returned by the server.
-        For example, if retrieving of a virtual machine fails because it
-        doesn't exist this attribute will contain the integer value 404. Note
-        that this may be `nil` if the error is not HTTP related.
-
-        `fault`:: The `Fault` object associated to the error.
         """
         super(Error, self).__init__(message)
+        """
+        Creates an instance of Error class.
+        """
         self.code = code
+        """
+        An error code associated to the error. For HTTP related
+        errors, this will be the HTTP response code returned by the server.
+        For example, if retrieving of a virtual machine fails because it
+        doesn't exist this attribute will contain the integer value 404. Note
+        that this may be `nil` if the error is not HTTP related."""
         self.fault = fault
+        """
+        The `Fault` object associated to the error.
+        """
 
 
 class AuthError(Error):
@@ -230,70 +234,87 @@ def __init__(
 
         This method supports the following parameters:
 
-        `url`:: A string containing the base URL of the server, usually
+        `url` \n
+        A string containing the base URL of the server, usually
         something like `https://server.example.com/ovirt-engine/api`.
 
-        `username`:: The name of the user, something like `admin@internal`.
+        `username` \n
+        The name of the user, something like `admin@internal`.
 
-        `password`:: The name password of the user.
+        `password` \n
+        The name password of the user.
 
-        `token`:: : The token to be used to access API. Optionally, user can
+        `token` \n
+        The token to be used to access API. Optionally, user can
         use token, instead of username and password to access API. If user
         don't specify `token` parameter, SDK will automatically create one.
 
-        `insecure`:: A boolean flag that indicates if the server TLS
+        `insecure` \n
+        A boolean flag that indicates if the server TLS
         certificate and host name should be checked.
 
-        `ca_file`:: A PEM file containing the trusted CA certificates. The
+        `ca_file` \n
+        A PEM file containing the trusted CA certificates. The
         certificate presented by the server will be verified using these CA
         certificates. If `ca_file` parameter is not set, system wide
         CA certificate store is used.
 
-        `debug`:: A boolean flag indicating if debug output should be
+        `debug` \n
+        A boolean flag indicating if debug output should be
         generated. If the value is `True` and the `log` parameter isn't
         `None` then the data sent to and received from the server will
         be written to the log. Be aware that user names and passwords will
         also be written, so handle it with care.
 
-        `log`:: The logger where the log messages will be written.
+        `log` \n
+        The logger where the log messages will be written.
 
-        `kerberos`:: A boolean flag indicating if Kerberos
+        `kerberos` \n
+        A boolean flag indicating if Kerberos
         authentication should be used instead of the default basic
         authentication.
 
-        `timeout`:: The maximum total time to wait for the response, in
+        `timeout` \n
+        The maximum total time to wait for the response, in
         seconds. A value of zero (the default) means wait for ever. If
         the timeout expires before the response is received an exception
         will be raised.
 
-        `compress`:: A boolean flag indicating if the SDK should ask
+        `compress` \n
+        A boolean flag indicating if the SDK should ask
         the server to send compressed responses. The default is `True`.
         Note that this is a hint for the server, and that it may return
         uncompressed data even when this parameter is set to `True`.
         Note that compression will be disabled if user pass `debug`
         parameter set to `true`, so the debug messages are in plain text.
 
-        `sso_url`:: A string containing the base SSO URL of the serve.
+        `sso_url` \n
+        A string containing the base SSO URL of the serve.
         Default SSO url is computed from the `url` if no `sso_url` is provided.
 
-        `sso_revoke_url`:: A string containing the base URL of the SSO
+        `sso_revoke_url` \n
+        A string containing the base URL of the SSO
         revoke service. This needs to be specified only when using
         an external authentication service. By default this URL
         is automatically calculated from the value of the `url` parameter,
         so that SSO token revoke will be performed using the SSO service
         that is part of the engine.
 
-        `sso_token_name`:: The token name in the JSON SSO response returned
+        `sso_token_name` \n
+        The token name in the JSON SSO response returned
         from the SSO server. Default value is `access_token`.
 
-        `headers`:: A dictionary with headers which should be send with every
+        `headers` \n
+        A dictionary with headers which should be send with every
         request.
 
-        `connections`:: The maximum number of connections to open to the host.
+        `connections` \n
+        The maximum number of connections to open to the host.
         If the value is `0` (the default) then the number of connections will
         be unlimited.
 
-        `pipeline`:: The maximum number of request to put in an HTTP pipeline
+        `pipeline` \n
+        The maximum number of request to put in an HTTP pipeline
         without waiting for the response. If the value is `0` (the default)
         then pipelining is disabled.
         """
@@ -360,7 +381,8 @@ def send(self, request):
 
         This method supports the following parameters.
 
-        `request`:: The Request object containing the details of the HTTP
+        `request` \n
+        The Request object containing the details of the HTTP
         request to send.
 
         The returned value is a Request object containing the details of the
@@ -445,7 +467,7 @@ def __send(self, request):
         for header_name, header_value in headers_dict.items():
             header_lines.append('%s: %s' % (header_name, header_value))
 
-        header_lines.append('User-Agent: PythonSDK/%s' % version.VERSION)
+        header_lines.append('User-Agent: PythonSDK/%s' % get_version())
         header_lines.append('Version: 4')
         header_lines.append('Content-Type: application/xml')
         header_lines.append('Accept: application/xml')
@@ -796,7 +818,7 @@ def close(self, logout=True):
         """
         Releases the resources used by this connection.
 
-        `logout`:: A boolean, which specify if token should be revoked,
+        `logout` A boolean, which specify if token should be revoked,
         and so user should be logged out.
         """
 
@@ -818,10 +840,10 @@ def _build_url(self, path='', query=None):
 
         This method supports the following parameters:
 
-        `path`:: The path that will be added to the base URL. The default is an
+        `path` The path that will be added to the base URL. The default is an
         empty string.
 
-        `query`:: A dictionary containing the query parameters to add to the
+        `query` A dictionary containing the query parameters to add to the
         URL. The keys of the dictionary should be strings containing the names
         of the parameters, and the values should be strings containing the
         values.
@@ -841,7 +863,7 @@ def check_xml_content_type(self, response):
          XML then it does nothing. If it isn't XML then it raises an
          exception.
 
-         `response`:: The HTTP response to check.
+         `response` The HTTP response to check.
         """
         return self._check_content_type(
             self.__XML_CONTENT_TYPE_RE,
@@ -855,7 +877,7 @@ def check_json_content_type(self, response):
          JSON then it does nothing. If it isn't JSON then it raises an
          exception.
 
-         `response`:: The HTTP response to check.
+         `response` The HTTP response to check.
         """
         return self._check_content_type(
             self.__JSON_CONTENT_TYPE_RE,
@@ -868,10 +890,10 @@ def _check_content_type(self, expected_re, expected_name, headers):
         Checks the given content type and raises an exception if it isn't the
         expected one.
 
-        `expected_re`:: The regular expression used to check the expected
+        `expected_re` The regular expression used to check the expected
                         content type.
-        `expected_name`:: The name of the expected content type.
-        `headers`:: The HTTP headers to check.
+        `expected_name` The name of the expected content type.
+        `headers` The HTTP headers to check.
         """
         content_type = self._get_header_value(headers, 'content-type')
         if expected_re.match(content_type) is None:
@@ -892,7 +914,7 @@ def _read_reponse(self, context):
         """
         Read the response.
 
-        `context`:: tuple which contains cur easy, response body,
+        `context` tuple which contains cur easy, response body,
         response headers, original request
         """
         # Extract the response code and body:
@@ -935,8 +957,8 @@ def _get_header_value(self, headers, name):
         """
         Return header value by its name.
 
-        `headers`:: list of headers
-        `name`:: name of the header
+        `headers` list of headers
+        `name` name of the header
         """
         return next(
             (h.split(':')[1].strip() for h in headers if h.lower().startswith(name)),
@@ -984,8 +1006,7 @@ class ConnectionBuilder(object):
     equivalent to calling the constructor of the `Connection`
     class. Typical use will be like this:
 
-    [source,python]
-    ----
+    ```python
     # Create the builder once:
     builder = ConnectionBuilder(
         url='https://enginer40.example.com/ovirt-engine/api',
@@ -1001,7 +1022,7 @@ class ConnectionBuilder(object):
     # Create and use a second connection:
     with builder.build() as connection:
        ...
-    ----
+    ```
     """
 
     def __init__(self, **kwargs):
@@ -1029,7 +1050,7 @@ def build(self):
 #   import ovirtsdk4 as sdk
 #   vm = sdk.types.Vm()
 #
-from ovirtsdk4 import readers  # noqa: F401
-from ovirtsdk4 import services  # noqa: F401
-from ovirtsdk4 import types  # noqa: F401
-from ovirtsdk4 import writers  # noqa: F401
+import ovirtsdk4.readers as readers  # noqa: F401
+import ovirtsdk4.writers as writers  # noqa: F401
+import ovirtsdk4.types as types  # noqa: F401
+import ovirtsdk4.services as services  # noqa: F401