initial build of docs

Author: gilesknap

.github/workflows/code.yml

@@ -36,6 +36,8 @@ jobs:
         uses: peaceiris/actions-gh-pages@bbdfb200618d235585ad98e965f4aafc39b4c501  # v3.7.3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
+          # deploy to the organization github.io
+          external_repository: ${{ github.repository_owner }}
           publish_dir: .github/pages
           keep_files: true
 
@@ -64,6 +66,8 @@ jobs:
         uses: peaceiris/actions-gh-pages@bbdfb200618d235585ad98e965f4aafc39b4c501  # v3.7.3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
+          # deploy to the organization github.io
+          external_repository: ${{ github.repository_owner }}
           publish_dir: build/html
           keep_files: true
 

.github/workflows/docs.yml renamed to .github/workflows/org_docs.yml

@@ -14,6 +14,7 @@
 
 sys.path.insert(0, os.path.abspath(os.path.join(__file__, "..", "..")))
 
+import k8s_epics_docs  # noqa
 
 # -- General configuration ------------------------------------------------
 

docs/conf.py

@@ -0,0 +1,5 @@
+Kubernetes for EPICS IOCs strategy
+==================================
+
+Todo
+

docs/explanations/strategy.rst

@@ -51,14 +51,15 @@ About the documentation
     :name: how-to
     :maxdepth: 1
 
-    how-to/accomplish-a-task
+    how-to/setup_k8s
+    how-to/manage_iocs
 
 .. toctree::
     :caption: Explanations
     :name: explanations
     :maxdepth: 1
 
-    explanations/why-is-something-so
+    explanations/strategy
 
 .. rst-class:: no-margin-after-ul
 
@@ -67,7 +68,7 @@ About the documentation
     :name: reference
     :maxdepth: 1
 
-    reference/api
+    reference/cli
     reference/contributing
 
 * :ref:`genindex`

docs/explanations/why-is-something-so.rst

@@ -1,7 +1,7 @@
 .. _CLI:
 
-CLI
-===
+Command Line Interface for IOC Management
+=========================================
 
 The Module k8s-epics-utils provides scripts that simplify common operations
 for deploying and managing IOCs with Kubernetes.

docs/index.rst

@@ -1,6 +1,12 @@
 Installation Tutorial
 =====================
 
+Intro
+----------------------------
+This project is documentation only but if you want to update the
+documentation and build it then follow these instructions
+
+
 Check your version of python
 ----------------------------
 
@@ -9,29 +15,15 @@ typing into a terminal::
 
     python3 --version
 
-Create a virtual environment
-----------------------------
-
-It is recommended that you install into a “virtual environment” so this
-installation will not interfere with any existing Python software::
-
-    python3 -m venv /path/to/venv
-    source /path/to/venv/bin/activate
-
-
-Installing the library
-----------------------
-
-You can now use ``pip`` to install the library::
+Use Pipenv to install developer tools
+-------------------------------------
 
-    python3 -m pip install k8s_epics_docs
+Install pipenv if you do not already have it https://pypi.org/project/pipenv/
 
-If you require a feature that is not currently released you can also install
-from github::
+    pipenv install --dev
 
-    python3 -m pip install git+git://github.com/epics-containers/k8s-epics-docs.git
 
-The library should now be installed and the commandline interface on your path.
-You can check the version that has been installed by typing::
+Building the documentation with sphinx
+--------------------------------------
 
-    k8s_epics_docs --version
+    pipenv run docs

docs/reference/cli.rst

@@ -29,6 +29,28 @@ include_package_data = False
 # Don't include our tests directory in the distribution
 exclude = tests
 
+[options.entry_points]
+# Include a command line script
+console_scripts =
+    k8s_epics_docs = k8s_epics_docs.cli:main
+
+[mypy]
+# Ignore missing stubs for modules we use
+ignore_missing_imports = True
+
+[isort]
+profile=black
+float_to_top=true
+skip=setup.py,conf.py,build
+
+[flake8]
+# Make flake8 respect black's line length (default 88),
+max-line-length = 88
+extend-ignore =
+    E203,  # See https://github.com/PyCQA/pycodestyle/issues/373
+    F811, # support typing.overload decorator
+    F722, # allow Annotated[typ, some_func("some string")]
+
 [tool:pytest]
 # Run pytest with all our checkers, and don't spam us with massive tracebacks on error
 addopts =

docs/tutorials/installation.rst

@@ -7,6 +7,16 @@
 import pytest
 
 
+@pytest.fixture
+def setupcfg():
+    import configparser
+
+    conf = configparser.ConfigParser()
+    conf.read("setup.cfg")
+
+    return conf["metadata"]
+
+
 def assert_not_contains_text(path, text, explanation):
     with open(path, "r") as f:
         contents = f.read().replace("\n", " ")