Merge pull request #108 from lubosmj/docs-building-2

Revert "Revert "Add a section for building docs""

.github/workflows/ci.yaml

@@ -75,6 +75,7 @@ jobs:
           cp oci_env/.github/assets/${TEST}_compose.env oci_env/compose.env
           cp oci_env/.github/assets/${TEST}_compose.env ${PWD}/custom.env
           echo "API_PORT=7210" >> ${PWD}/custom.env
+          echo "DOCS_PORT=12346" >> ${PWD}/custom.env
           echo "COMPOSE_PROJECT_NAME=my_2nd_project" >> ${PWD}/custom.env
           echo "SECOND_SERVICE_PORT=7002" >> ${PWD}/custom.env
 

README.md

@@ -201,6 +201,19 @@ Please note that `host.containers.internal` points to the wrong interface in `po
 using `podman` < 4.1, you need modify `/etc/hosts` inside the container running Pulp with the IP
 address for the publicly facing network interface on the host.
 
+
+#### Building docs
+
+First, navigate to `/src/{plugin}/docs` in the container and do the following:
+```
+pip3 install -r ../doc_requirements.txt
+make clean && make diagrams && make html
+python3 -m http.server ${DOCS_PORT}
+```
+
+Then, visit `0.0.0.0:${DOCS_PORT}` in a web browser to preview the documentation.
+
+
 ### Unit
 
 ```bash

base/compose.yaml

@@ -23,6 +23,8 @@ services:
       - "API_HOST={API_HOST}"
       - "API_PORT={API_PORT}"
       - "API_PROTOCOL={API_PROTOCOL}"
+      - "DOCS_PORT={DOCS_PORT}"
+      - "NGINX_DOCS_PORT={NGINX_DOCS_PORT}"
       - "REMOTE_FIXTURES_ORIGIN={REMOTE_FIXTURES_ORIGIN}"
       - "NGINX_PORT={NGINX_PORT}"
       - "NGINX_SSL_PORT={NGINX_SSL_PORT}"
@@ -31,6 +33,7 @@ services:
 
     ports:
       - "{API_PORT}:{NGINX_PORT}"
+      - "{DOCS_PORT}:{NGINX_DOCS_PORT}"
     depends_on:
       - _base
     volumes:

client/oci_env/utils.py

@@ -71,6 +71,10 @@ def get_config(env_file):
         "API_PROTOCOL": "http",
         "API_HOST": "localhost",
         "API_PORT": "5001",
+
+        # A port dedicated for exposing generated docs
+        "DOCS_PORT": "12345",
+        "NGINX_DOCS_PORT": user_preferences.get("DOCS_PORT", "12345"),
 
         # nginx port to run in the container. This defaults to 5001 if nothing is set or
         # the value of API_HOST if that is set.

compose.env.example

@@ -17,4 +17,5 @@ DEV_SOURCE_PATH=
 # Port, hostname and protocol used to configure pulp content origin
 # API_HOST=localhost
 # API_PORT=5001
-# API_PROTOCOL=http
+# API_PROTOCOL=http
+# DOCS_PORT=12345