Sphinx configured to process docstrings

* Sphinx configured to create html documentation from docstrings on API. Low level and deprecated classes not included in index. * Downgraded urllib3 in setup.cfg * Updated some docstrings after seeing the results from Sphinx Signed-off-by: Jhon Honce <[email protected]>
kajal072001 · May 6, 2021 · 115a27f · 115a27f
1 parent 003423b
commit 115a27f
Show file tree

Hide file tree

Showing 13 changed files with 195 additions and 37 deletions.
diff --git a/Makefile b/Makefile
@@ -14,7 +14,6 @@ export PODMAN_VERSION ?= "3.2.0"
 podman-py:
 	rm dist/* || :
 	python -m pip install --user -r requirements.txt
-	python -m pip install --user -r test-requirements.txt
 	PODMAN_VERSION=$(PODMAN_VERSION) \
 	$(PYTHON) setup.py sdist bdist bdist_wheel
 
@@ -24,6 +23,7 @@ lint:
 
 .PHONY: tests
 tests:
+	python -m pip install --user -r test-requirements.txt
 	DEBUG=1 coverage run -m unittest discover -s podman/tests
 	coverage report -m --skip-covered --fail-under=80 --omit=./podman/tests/* --omit=.tox/* \
 	--omit=/usr/lib/* --omit=*/lib/python*
@@ -52,7 +52,9 @@ release:
 docs:
 	mkdir -p build/docs/source
 	cp -R docs/source/* build/docs/source
-	sphinx-apidoc -f -o build/docs/source podman podman/tests podman/api_connection.py podman/containers podman/images \
+	sphinx-apidoc --separate --no-toc --force --templatedir build/docs/source/_templates/apidoc \
+		-o build/docs/source \
+		podman podman/tests podman/api_connection.py podman/containers podman/images \
 		podman/manifests podman/networks podman/pods podman/system
 	sphinx-build build/docs/source build/html
 
@@ -77,7 +79,7 @@ uninstall:
 
 .PHONY: clean
 clean:
-	rm -rf podman_py.egg-info dist build/docs
+	rm -rf podman_py.egg-info dist build/*
 	find . -depth -name __pycache__ -exec rm -rf {} \;
 	find . -depth -name \*.pyc -exec rm -f {} \;
 	$(PYTHON) ./setup.py clean --all

diff --git a/docs/source/_static/about.html b/docs/source/_static/about.html
@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>About PodmanPy</title>
+</head>
+<body>
+About PodmanPy
+</body>
+</html>
diff --git a/docs/source/_static/podman-logo.ico b/docs/source/_static/podman-logo.ico
diff --git a/docs/source/_static/podman-logo.png b/docs/source/_static/podman-logo.png
diff --git a/docs/source/_templates/apidoc/module.rst_t b/docs/source/_templates/apidoc/module.rst_t
@@ -0,0 +1,9 @@
+{%- if show_headings %}
+{{- basename | replace("podman.", "") | e | heading }}
+
+{% endif -%}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+   :{{ option }}:
+{%- endfor %}
+
diff --git a/docs/source/_templates/apidoc/package.rst_t b/docs/source/_templates/apidoc/package.rst_t
@@ -0,0 +1,53 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+   :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{%- macro toctree(docnames) -%}
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+{%- endmacro %}
+
+{%- if is_namespace %}
+{{- [pkgname, "namespace"] | join(" ") | e | heading }}
+{% else %}
+{{- [pkgname, "package"] | join(" ") | e | heading }}
+{% endif %}
+
+{%- if modulefirst and not is_namespace %}
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
+
+{%- if subpackages %}
+Subpackages
+-----------
+
+{{ toctree(subpackages) }}
+{% endif %}
+
+{%- if submodules %}
+Submodules
+----------
+{% if separatemodules %}
+{{ toctree(submodules) }}
+{% else %}
+{%- for submodule in submodules %}
+{% if show_headings %}
+{{- [submodule, "module"] | join(" ") | e | heading(2) }}
+{% endif %}
+{{ automodule(submodule, automodule_options) }}
+{% endfor %}
+{%- endif %}
+{%- endif %}
+
+{%- if not modulefirst and not is_namespace %}
+Module contents
+---------------
+
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
diff --git a/docs/source/_templates/apidoc/toc.rst_t b/docs/source/_templates/apidoc/toc.rst_t
@@ -0,0 +1,8 @@
+{{ header | heading }}
+
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -20,12 +20,13 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'Podman SDK for Python'
-copyright = '2021 Red Hat, Inc'
-author = 'Red Hat'
+project = u'Podman Python SDK'
+copyright = u'2021, Red Hat Inc'
+author = u'Red Hat Inc'
 
 # The full version, including alpha/beta/rc tags
-release = '3.1.2.1'
+version = '3.1.2.1'
+release = version
 
 add_module_names = False
 
@@ -34,7 +35,12 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
+# isort: unique-list
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -50,11 +56,31 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-# html_theme = 'alabaster'
-html_theme = 'default'
+html_theme = 'alabaster'
+html_favicon = '_static/podman-logo.ico'
 html_theme_options = {
-    'description': 'A Python library for the Podman service API',
-    'fixed_sidebar': True,
+    'description': 'Develop scripted Podman operations',
+    'fixed_sidebar': False,
+    'github_banner': True,
+    'github_repo': 'podman-py',
+    'github_user': 'containers',
+    'logo': "podman-logo.png",
+    'logo_name': True,
+    'show_powered_by': False,
+    'extra_nav_links': {
+        'Report PodmanPy Issue': 'http://github.com/containers/podman-py/issues',
+        'Podman Reference': 'http://docs.podman.io',
+        'Podman on github': 'http://github.com/containers/podman',
+    },
+}
+
+html_sidebars = {
+    '**': [
+        'about.html',
+        'navigation.html',
+        'relations.html',
+        'searchbox.html',
+    ]
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -63,6 +89,12 @@
 html_static_path = ['_static']
 
 #  -- autoclass settings ------------------------------------------------------	s
+autodoc_member_order = "groupwise"
+autodoc_default_options = {
+    'members': True,
+    'inherited-members': True,
+    'show-inheritance': True,
+}
 autoclass_content = "both"
 
 #  -- Napoleon settings ------------------------------------------------------	s

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,24 +1,70 @@
+PodmanPy: Python scripting for Podman services
+==============================================
+.. image:: https://img.shields.io/pypi/l/podman-py.svg
+    :target: https://pypi.org/project/podman-py/
 
-.. image:: https://github.com/containers/podman/blob/master/logo/podman-logo.png?raw=true
+.. image:: https://img.shields.io/pypi/wheel/podman-py.svg
+    :target: https://pypi.org/project/podman-py/
 
-What is PodmanPy?
-====================================
+.. image:: https://img.shields.io/pypi/pyversions/podman-py.svg
+    :target: https://pypi.org/project/podman-py/
 
 PodmanPy is a Python3 module that allows you to write Python scripts that access resources
-maintained by a Podman service.
+maintained by a Podman service. It leverages the Podman service RESTful API.
 
-PodmanPy leverages the Podman service RESTful API. Connections via http+ssh://, http+unix:// or
-tcp:// are supported.
+Podman services are addressed using a URL where the scheme signals to the client how to connect to
+service. Supported schemes are: ``http+ssh``, ``http+unix`` or ``tcp``. Formats are the following styles:
 
-.. automodule:: podman
-    :members:
-    :inherited-members:
+ - ``http+ssh://[<login>@]<hostname>[:<port>]/<full filesystem path>``
+
+   - ``http+ssh://[email protected]:22/run/user/1000/podman/podman.sock``
+   - The scheme ``ssh`` is excepted as an alias
+
+ - ``http+unix://<full filesystem path>``
+
+   - ``http+unix:///run/podman/podman.sock``
+   - The scheme ``unix`` is excepted as an alias
+
+ - ``tcp://<hostname>:<port>``
+
+   - ``tcp://api.example:8888``
+
+Example
+-------
+.. code-block:: python
+   :linenos:
+
+    import podman
+
+    with podman.Client() as client:
+        if client.ping():
+            images = client.images.list()
+            for image in images:
+                print(image.id)
+
+.. toctree::
+   :caption: Podman Client
+   :maxdepth: 2
+
+   podman.client
 
 .. toctree::
-    :maxdepth: 2
-    :caption: Contents:
+   :caption: Podman Entities
+   :glob:
+   :hidden:
 
-   modules
+   podman.domain.containers
+   podman.domain.containers_manager
+   podman.domain.images
+   podman.domain.images_manager
+   podman.domain.events*
+   podman.domain.manifests*
+   podman.domain.networks*
+   podman.domain.pods*
+   podman.domain.secrets*
+   podman.domain.system*
+   podman.domain.volume*
+   podman.errors.exceptions
 
 Indices and tables
 ==================

diff --git a/podman/domain/containers.py b/podman/domain/containers.py
@@ -93,9 +93,6 @@ def commit(self, repository: str = None, tag: str = None, **kwargs) -> Image:
             format (str): Format of the image manifest and metadata
             message (str): Commit message to include with Image
             pause (bool): Pause the container before committing it
-
-        Notes:
-            See https://docs.podman.io/en/latest/_static/api.html#operation/libpodCommitContainer
         """
         params = {
             "author": kwargs.get("author"),

diff --git a/podman/domain/images.py b/podman/domain/images.py
@@ -44,23 +44,23 @@ def history(self) -> List[Dict[str, Any]]:
         response.raise_for_status(not_found=ImageNotFound)
         return response.json()
 
-    def remove(self, **kwargs) -> List[Dict[str, Union[str, int]]]:
+    def remove(
+        self, **kwargs
+    ) -> List[Dict[api.Literal["Deleted", "Untagged", "Errors", "ExitCode"], Union[str, int]]]:
         """Delete image from Podman service.
 
+        Podman only
+
         Keyword Args:
             force: Delete Image even if in use
             noprune: Ignored.
 
         Returns:
-            List[Dict[Literal["Deleted", "Untagged", "Errors", "ExitCode"], Union[str, int]]]
+            Report on which images were deleted and untagged, including any reported errors.
 
         Raises:
             ImageNotFound: when image does not exist
             APIError: when service returns an error
-
-        Notes:
-            - Podman only
-            - The dictionaries with keys Errors and ExitCode are added.
         """
         return self.manager.remove(self.id, **kwargs)
 
@@ -71,16 +71,15 @@ def save(
     ) -> Iterator[bytes]:
         """Returns Image as tarball.
 
+        Format is set to docker-archive, this allows load() to import this tarball.
+
         Args:
             chunk_size: If None, data will be streamed in received buffer size.
                 If not None, data will be returned in sized buffers. Default: 2MB
             named: Ignored.
 
         Raises:
             APIError: when service returns an error
-
-        Notes:
-            Format is set to docker-archive, this allows load() to import this tarball.
         """
         response = self.client.get(
             f"/images/{self.id}/get", params={"format": ["docker-archive"]}, stream=True

diff --git a/setup.cfg b/setup.cfg
@@ -33,7 +33,8 @@ test_suite =
 install_requires =
     requests>=2.24
     toml>=0.10.2
-    urllib3~=1.26.4
+    urllib3~=1.24.2
+    pyxdg~=0.26
 
 [bdist_wheel]
 # python < 3.6 not supported

diff --git a/test-requirements.txt b/test-requirements.txt
@@ -1,3 +1,4 @@
+-r requirements.txt
 black
 coverage
 fixtures~=3.0.0