Fix up docs and format issues

Clean up some format issues and also fix the command to build the docs so that is built accurately and in the right location for it to show up in readthedocs. Signed-off-by: Urvashi Mohnani <[email protected]>
containers · Nov 7, 2023 · c8113a0 · c8113a0
1 parent 6edcd2d
commit c8113a0
Show file tree

Hide file tree

Showing 21 changed files with 445 additions and 274 deletions.
diff --git a/Makefile b/Makefile
@@ -76,7 +76,7 @@ docs:
 	# -D language=en : define language as en
 	# . : source directory
 	# _build/html : target
-	cd _build/doctrees && python3 -m sphinx -T -E -W --keep-going -b html -d _build/doctrees -D language=en . _build/html
+	python3 -m sphinx -T -E -W --keep-going -b html -d _build/doctrees -D language=en _build/doctrees _build/html
 
 .PHONY: rpm
 rpm: ## Build rpm packages

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -39,7 +39,7 @@
 # sphinx.ext.napoleon: Support for NumPy and Google style docstrings
 # sphinx.ext.viewcode: Add links to highlighted source code
 # isort: unique-list
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.viewcode']
+extensions = ['sphinx.ext.napoleon', 'sphinx.ext.autodoc', 'sphinx.ext.viewcode']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -51,6 +51,9 @@
 exclude_patterns = [
     'podman.api.*rst',
     'podman.rst',
+    'podman.version.rst',
+    'podman.tlsconfig.rst',
+    'podman.errors.rst',
 ]
 
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -53,14 +53,18 @@ Example
    :glob:
    :hidden:
 
+   podman.domain.config*
    podman.domain.containers
    podman.domain.containers_manager
    podman.domain.images
    podman.domain.images_manager
+   podman.domain.ipam*
    podman.domain.events*
+   podman.domain.manager
    podman.domain.manifests*
    podman.domain.networks*
    podman.domain.pods*
+   podman.domain.registry_data*
    podman.domain.secrets*
    podman.domain.system*
    podman.domain.volume*

diff --git a/podman/domain/containers.py b/podman/domain/containers.py
@@ -82,7 +82,10 @@ def attach_socket(self, **kwargs):
         """
         raise NotImplementedError()
 
-    def commit(self, repository: str = None, tag: str = None, **kwargs) -> Image:
+    def commit(self,
+               repository: str = None,
+               tag: str = None,
+               **kwargs) -> Image:
         """Save container to given repository.
 
         Args:
@@ -140,7 +143,8 @@ def exec_run(
         environment: Union[Mapping[str, str], List[str]] = None,
         workdir: str = None,
         demux: bool = False,
-    ) -> Tuple[Optional[int], Union[Iterator[bytes], Any, Tuple[bytes, bytes]]]:
+    ) -> Tuple[Optional[int], Union[Iterator[bytes], Any, Tuple[bytes,
+                                                                bytes]]]:
         """Run given command inside container and return results.
 
         Args:
@@ -187,20 +191,24 @@ def exec_run(
             "WorkingDir": workdir,
         }
         # create the exec instance
-        response = self.client.post(f"/containers/{self.name}/exec", data=json.dumps(data))
+        response = self.client.post(f"/containers/{self.name}/exec",
+                                    data=json.dumps(data))
         response.raise_for_status()
         exec_id = response.json()['Id']
         # start the exec instance, this will store command output
-        start_resp = self.client.post(
-            f"/exec/{exec_id}/start", data=json.dumps({"Detach": detach, "Tty": tty})
-        )
+        start_resp = self.client.post(f"/exec/{exec_id}/start",
+                                      data=json.dumps({
+                                          "Detach": detach,
+                                          "Tty": tty
+                                      }))
         start_resp.raise_for_status()
         # get and return exec information
         response = self.client.get(f"/exec/{exec_id}/json")
         response.raise_for_status()
         return response.json().get('ExitCode'), start_resp.content
 
-    def export(self, chunk_size: int = api.DEFAULT_CHUNK_SIZE) -> Iterator[bytes]:
+    def export(self,
+               chunk_size: int = api.DEFAULT_CHUNK_SIZE) -> Iterator[bytes]:
         """Download container's filesystem contents as a tar archive.
 
         Args:
@@ -213,14 +221,17 @@ def export(self, chunk_size: int = api.DEFAULT_CHUNK_SIZE) -> Iterator[bytes]:
             NotFound: when container has been removed from service
             APIError: when service reports an error
         """
-        response = self.client.get(f"/containers/{self.id}/export", stream=True)
+        response = self.client.get(f"/containers/{self.id}/export",
+                                   stream=True)
         response.raise_for_status()
 
         for out in response.iter_content(chunk_size=chunk_size):
             yield out
 
     def get_archive(
-        self, path: str, chunk_size: int = api.DEFAULT_CHUNK_SIZE
+        self,
+        path: str,
+        chunk_size: int = api.DEFAULT_CHUNK_SIZE
     ) -> Tuple[Iterable, Dict[str, Any]]:
         """Download a file or folder from the container's filesystem.
 
@@ -232,7 +243,8 @@ def get_archive(
             First item is a raw tar data stream.
             Second item is a dict containing os.stat() information on the specified path.
         """
-        response = self.client.get(f"/containers/{self.id}/archive", params={"path": [path]})
+        response = self.client.get(f"/containers/{self.id}/archive",
+                                   params={"path": [path]})
         response.raise_for_status()
 
         stat = response.headers.get("x-docker-container-path-stat", None)
@@ -255,7 +267,8 @@ def kill(self, signal: Union[str, int, None] = None) -> None:
         Raises:
             APIError: when service reports an error
         """
-        response = self.client.post(f"/containers/{self.id}/kill", params={"signal": signal})
+        response = self.client.post(f"/containers/{self.id}/kill",
+                                    params={"signal": signal})
         response.raise_for_status()
 
     def logs(self, **kwargs) -> Union[bytes, Iterator[bytes]]:
@@ -286,7 +299,9 @@ def logs(self, **kwargs) -> Union[bytes, Iterator[bytes]]:
             "until": api.prepare_timestamp(kwargs.get("until")),
         }
 
-        response = self.client.get(f"/containers/{self.id}/logs", stream=stream, params=params)
+        response = self.client.get(f"/containers/{self.id}/logs",
+                                   stream=stream,
+                                   params=params)
         response.raise_for_status()
 
         if stream:
@@ -318,9 +333,9 @@ def put_archive(self, path: str, data: bytes = None) -> bool:
         if data is None:
             data = api.create_tar("/", path)
 
-        response = self.client.put(
-            f"/containers/{self.id}/archive", params={"path": path}, data=data
-        )
+        response = self.client.put(f"/containers/{self.id}/archive",
+                                   params={"path": path},
+                                   data=data)
         return response.ok
 
     def remove(self, **kwargs) -> None:
@@ -344,7 +359,8 @@ def rename(self, name: str) -> None:
         if not name:
             raise ValueError("'name' is a required argument.")
 
-        response = self.client.post(f"/containers/{self.id}/rename", params={"name": name})
+        response = self.client.post(f"/containers/{self.id}/rename",
+                                    params={"name": name})
         response.raise_for_status()
 
         self.attrs["Name"] = name  # shortcut to avoid needing reload()
@@ -360,7 +376,8 @@ def resize(self, height: int = None, width: int = None) -> None:
             "h": height,
             "w": width,
         }
-        response = self.client.post(f"/containers/{self.id}/resize", params=params)
+        response = self.client.post(f"/containers/{self.id}/resize",
+                                    params=params)
         response.raise_for_status()
 
     def restart(self, **kwargs) -> None:
@@ -374,7 +391,9 @@ def restart(self, **kwargs) -> None:
         if kwargs.get("timeout"):
             post_kwargs["timeout"] = float(params["timeout"]) * 1.5
 
-        response = self.client.post(f"/containers/{self.id}/restart", params=params, **post_kwargs)
+        response = self.client.post(f"/containers/{self.id}/restart",
+                                    params=params,
+                                    **post_kwargs)
         response.raise_for_status()
 
     def start(self, **kwargs) -> None:
@@ -384,13 +403,14 @@ def start(self, **kwargs) -> None:
             detach_keys: Override the key sequence for detaching a container (Podman only)
         """
         response = self.client.post(
-            f"/containers/{self.id}/start", params={"detachKeys": kwargs.get("detach_keys")}
-        )
+            f"/containers/{self.id}/start",
+            params={"detachKeys": kwargs.get("detach_keys")})
         response.raise_for_status()
 
     def stats(
         self, **kwargs
-    ) -> Union[bytes, Dict[str, Any], Iterator[bytes], Iterator[Dict[str, Any]]]:
+    ) -> Union[bytes, Dict[str, Any], Iterator[bytes], Iterator[Dict[str,
+                                                                     Any]]]:
         """Return statistics for container.
 
         Keyword Args:
@@ -410,7 +430,9 @@ def stats(
             "stream": stream,
         }
 
-        response = self.client.get("/containers/stats", params=params, stream=stream)
+        response = self.client.get("/containers/stats",
+                                   params=params,
+                                   stream=stream)
         response.raise_for_status()
 
         if stream:
@@ -432,7 +454,9 @@ def stop(self, **kwargs) -> None:
         if kwargs.get("timeout"):
             post_kwargs["timeout"] = float(params["timeout"]) * 1.5
 
-        response = self.client.post(f"/containers/{self.id}/stop", params=params, **post_kwargs)
+        response = self.client.post(f"/containers/{self.id}/stop",
+                                    params=params,
+                                    **post_kwargs)
         response.raise_for_status()
 
         if response.status_code == requests.codes.no_content:
@@ -443,7 +467,9 @@ def stop(self, **kwargs) -> None:
                 return
 
         body = response.json()
-        raise APIError(body["cause"], response=response, explanation=body["message"])
+        raise APIError(body["cause"],
+                       response=response,
+                       explanation=body["message"])
 
     def top(self, **kwargs) -> Union[Iterator[Dict[str, Any]], Dict[str, Any]]:
         """Report on running processes in the container.
@@ -462,7 +488,9 @@ def top(self, **kwargs) -> Union[Iterator[Dict[str, Any]], Dict[str, Any]]:
             "stream": stream,
             "ps_args": kwargs.get("ps_args"),
         }
-        response = self.client.get(f"/containers/{self.id}/top", params=params, stream=stream)
+        response = self.client.get(f"/containers/{self.id}/top",
+                                   params=params,
+                                   stream=stream)
         response.raise_for_status()
 
         if stream:
@@ -481,7 +509,8 @@ def update(self, **kwargs):
         Raises:
             NotImplementedError: Podman service unsupported operation.
         """
-        raise NotImplementedError("Container.update() is not supported by Podman service.")
+        raise NotImplementedError(
+            "Container.update() is not supported by Podman service.")
 
     def wait(self, **kwargs) -> int:
         """Block until the container enters given state.
@@ -515,6 +544,7 @@ def wait(self, **kwargs) -> int:
         # This API endpoint responds with a JSON encoded integer.
         # See:
         # https://docs.podman.io/en/latest/_static/api.html#tag/containers/operation/ContainerWaitLibpod
-        response = self.client.post(f"/containers/{self.id}/wait", params=params)
+        response = self.client.post(f"/containers/{self.id}/wait",
+                                    params=params)
         response.raise_for_status()
         return response.json()