Improve documentation content

docs/api/ds_pycontain.rst

@@ -4,10 +4,10 @@ ds_pycontain code documentation
 Submodules
 ----------
 
-ds_pycontain.hello module
+ds_pycontain.docker_containers module
 ----------------------------------------------------
 
-.. automodule:: ds_pycontain.hello
+.. automodule:: ds_pycontain.docker_containers
    :members:
    :undoc-members:
    :show-inheritance:

docs/code_documentation.md

@@ -1,16 +1,28 @@
 # Code documentation
 
-```{hint}
+**ds_pycontain** is a python package which provides an abstraction over the docker API.
 
-  To add your code use sphinx tool in project root directory:
+Supported functionality covers:
+- Building docker images from Dockerfiles
+- Pulling docker images from dockerhub (or similar)
+- Running docker containers to execute a one-off command
+- Running docker containers to execute a long-running process and communicate with it
 
-    $ sphinx-apidoc -o docs/api/ src/ds_pycontain
-
-  and add reference from any page which is reachable from the index page.
-```
 
 ```python
-    import ds_pycontain
+  from ds_pycontain import DockerContainer, DockerImage, get_docker_client
+
+  client = get_docker_client()
+
+  # This will fetch the image from dockerhub if it is not already present
+  # with the "latest" tag. Then container is started and commands are run
+  with DockerContainer(DockerImage.from_tag("alpine")) as container:
+      ret_code, output = container.run("touch /animal.txt")
+      assert ret_code == 0
+
+      ret_code, output = container.run("ls /")
+      assert ret_code == 0
+      assert cast(bytes, output).find(b"animal.txt") >= 0
 ```
 
 ```{toctree}

docs/conf.py

@@ -6,8 +6,8 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'pycontain'
-copyright = '2023, ds'
+project = 'ds_pycontain'
+copyright = '2023, deepsense.ai'
 author = 'deepsense.ai'
 
 # -- General configuration ---------------------------------------------------
@@ -20,7 +20,6 @@
     "sphinx.ext.intersphinx", # allows to cross reference other sphinx documentations
     "sphinx.ext.autosectionlabel", # each doc section gets automatic reference generated
     "myst_parser", # adds support for Markdown
-    "sphinxcontrib.mermaid", # allows to use Mermaid diagrams
 ]
 
 templates_path = ['_templates']
@@ -35,8 +34,6 @@
 # Mapping to link other documentations
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
-    "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),
-    "numpy": ("https://numpy.org/doc/stable", None),
 }
 
 

docs/index.rst

@@ -2,10 +2,19 @@
    You can adapt this file completely to your preferences, but it should at least
    contain the root `toctree` directive.
 
-ds - pycontain
+`deepsense.ai <https://deepsense.ai>`_  - pycontain
 ====================================================================================================================
 
-Documentation for `ds_pycontain` python package.
+Documentation for **ds_pycontain** python package to work with docker containers and images.
+
+Example use case you might consider is to isolate python code execution generated by untrusted LLM by running it in a docker container.
+
+This package makes it a bit easier to:
+
+* Build docker images from Dockerfiles or in-memory string.
+* Pull docker images from dockerhub (or similar).
+* Run docker container to execute a one-off command.
+* Run docker container to execute a long-running process and communicate with it.
 
 
 .. toctree::

docs/project_overview.md

@@ -1,14 +1,6 @@
 # Project overview
 
-This is introduction to the project.
+The docker API is quite complicated and not well documented or typed.
+This project aims to provide a higher level abstraction over the docker API.
 
-Write here what this project is about, what problems does it solves on high level.
-
-You can also use [mermaid](https://mermaid.js.org/) - read more on [extension page](https://github.com/mgaitan/sphinxcontrib-mermaid):
-
-```{mermaid}
-  graph TD;
-      ds_pycontain --> B;
-      ds_pycontain --> C;
-      B --> D;
-```
+Main motivation is to allow to orchestrate running unsafe code or commands in isolated environment.

src/ds_pycontain/docker_containers.py

@@ -34,8 +34,6 @@ class DockerImage:
     """Represents a locally available docker image as a tag.
     You can either use existing docker image or build a new one from Dockerfile.
 
-    :example usage:
-
     >>> image = DockerImage.from_tag("alpine")
     >>> image = DockerImage.from_tag("python", tag="3.9-slim")
     >>> image = DockerImage.from_dockerfile("example/Dockerfile")
@@ -78,7 +76,7 @@ def exists(cls, name: str) -> bool:
 
     @classmethod
     def remove(cls, name: str) -> None:
-        """WARNING: Removes image from the system, be cautious with this function.
+        """**WARNING:** Removes image from the system, be cautious with this function.
         It is irreversible operation!.
         :param name: docker image name with tag, e.g. "alpine:latest"
         """
@@ -95,8 +93,11 @@ def from_tag(
     ) -> "DockerImage":
         """Use image with a given repository and tag. It is going to pull it if it is
         not present on the system.
-        Example: repository = "alpine" (will get "latest" tag)
-        Example: repository = "python" tag = "3.9-slim"
+
+        **Examples:**
+
+        >>> repository = "alpine" # (will get "latest" tag)
+        >>> repository = "python", tag = "3.9-slim"
 
         :param repository: docker image repository, e.g. "alpine".
         :param tag: docker image tag, e.g. "latest".
@@ -174,12 +175,15 @@ def from_dockerfile_content(
 class DockerContainer:
     """An isolated environment for running commands, based on docker container.
 
-    Examples:
+    **Examples:**
+
     If you need to run container for a single job:
+
     >>> container = DockerContainer(DockerImage.from_tag("alpine"))
     >>> status_code, logs = container.spawn_run("echo hello world")
 
     To run a container in background and execute commands:
+
     >>> with DockerContainer(DockerImage.from_tag("alpine")) as container:
     >>>     status_code, logs = container.run("echo hello world")
     """