Skip to content

Commit 2ad78a5

Browse files
tallpresstallpress
authored
feat: documentation genereated on orphan branch (#89)
* feat: documentation genereated on orphan branch * force push * try read the docs out * force readthedocs * check rdtd integration works * another force * test tagging * dont filter * check env var * finish off docs * clean up cmds in docs workflow * try using outputs * uses github outputs * uses " * build dev docs on push to development * adds autodoc tool to dev deps as well * Revert "adds autodoc tool to dev deps as well" This reverts commit 96ae876. * tidy up * remove requirements * tidy readme Co-authored-by: Tom Allpress <tom@automata.tech>
1 parent 32ea050 commit 2ad78a5

13 files changed

+281
-1
lines changed

‎.github/workflows/dev-docs.yml

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: Build development documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- development
7+
8+
jobs:
9+
docs:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Install dependencies
13+
run: pip install Sphinx m2r2
14+
- name: Checkout repo
15+
uses: actions/checkout@v2
16+
- name: Create a new branch for docs
17+
run: git checkout --orphan docs/development
18+
- name: Update the docs
19+
run: |
20+
make -C docs api_docs
21+
- name: Setup git agent and commit changes
22+
run: |
23+
git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/automata-tech/eva_python_sdk
24+
git config --global user.email "docs@automata.tech"
25+
git config --global user.name "docs-bot"
26+
git commit -am 'docs'
27+
git push origin docs/development -f

‎.github/workflows/docs.yml

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Build documentation
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*.*.*'
7+
8+
jobs:
9+
docs:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Install dependencies
13+
run: pip install Sphinx m2r2
14+
- name: Checkout repo
15+
uses: actions/checkout@v2
16+
- name: Get incoming tags
17+
run: echo "::set-output name=git-tag::$(git describe --tags --abbrev=0)"
18+
id: get-git-tag
19+
- name: Create a new branch for docs
20+
run: git checkout --orphan docs/${{ steps.get-git-tag.outputs.git-tag }}
21+
- name: Update the docs
22+
run: |
23+
make -C docs api_docs
24+
- name: Setup git agent and commit changes
25+
run: |
26+
git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/automata-tech/eva_python_sdk
27+
git config --global user.email "docs@automata.tech"
28+
git config --global user.name "docs-bot"
29+
git commit -am 'docs'
30+
git push origin docs/${{ steps.get-git-tag.outputs.git-tag }} -f

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,6 @@ dist/
66
.pytest_cache
77
*coverage*
88
.mypy_cache
9+
docs/_build
10+
docs/_static
11+
docs/_templates

‎.readthedocs.yaml

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# .readthedocs.yaml
2+
# Read the Docs configuration file
3+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
4+
5+
# Required
6+
version: 2
7+
8+
# Build documentation in the docs/ directory with Sphinx
9+
sphinx:
10+
configuration: docs/conf.py
11+
12+
13+
# Optionally set the version of Python and requirements required to build your docs
14+
# RTD currently doesn't support pipenv (Pipfile) for listing the requirements.
15+
python:
16+
version: "3.6"

‎Pipfile

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ pytest = "*"
2121
"pytest-flake8" = "*"
2222
"pytest-mypy" = "*"
2323
mypy = "*"
24+
Sphinx = "*"
25+
m2r2 = "*"
2426
# FIXME: why the hell is flake8 not including this correctly?
2527
"importlib-metadata" = "*"
2628
# FIXME: whyyyyyyyyyy

‎README.md

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Eva Python SDK [![PyPI version](https://badge.fury.io/py/evasdk.svg)](https://badge.fury.io/py/evasdk) ![Build status](https://github.com/automata-tech/eva_python_sdk/workflows/Build%20and%20test/badge.svg) [![codecov](https://codecov.io/gh/automata-tech/eva_python_sdk/branch/development/graph/badge.svg)](https://codecov.io/gh/automata-tech/eva_python_sdk)
1+
# Eva Python SDK
2+
3+
[![PyPI version](https://badge.fury.io/py/evasdk.svg)](https://badge.fury.io/py/evasdk) ![Build status](https://github.com/automata-tech/eva_python_sdk/workflows/Build%20and%20test/badge.svg) [![codecov](https://codecov.io/gh/automata-tech/eva_python_sdk/branch/development/graph/badge.svg)](https://codecov.io/gh/automata-tech/eva_python_sdk)
24

35
The Eva Python SDK provides convenient access to the Automata Eva API from applications written in Python 3.
46

@@ -16,6 +18,7 @@ __* This SDK is currently in beta__
1618
- [Logging](#logging)
1719
- [Bugs and feature requests](#bugs-and-feature-requests)
1820
- [Testing](#testing)
21+
- [Documentation](#documentation)
1922
- [License](#license)
2023

2124
## Installation
@@ -174,6 +177,31 @@ $ pipenv run test --runrobot --ip 172.16.16.2 --token abc-123-def-456
174177
$ pipenv run test -h
175178
```
176179

180+
## Documentation
181+
182+
Find the documentation [here](https://eva-python-sdk.readthedocs.io/en/latest/).
183+
184+
We are using [Sphinx](https://github.com/sphinx-doc/sphinx) to generate documentation, and the documentation is deployed with [Read The Docs](https://github.com/readthedocs/readthedocs.org).
185+
186+
We have added a few extensions to Sphinx
187+
- **sphinx.ext.autodoc** to automatically generate package documentation based off of Python docstrings.
188+
- **m2r2** to convert rST to MD, this is so we can include `README.md` to the online docs.
189+
190+
We have a *GitHub Action* in the `build.yaml` workflow that will do this automatically update the documentation and commit the documentation changes on pushing a branch to GitHub. For this we are using [EndBug/add-and-commit](https://github.com/EndBug/add-and-commit).
191+
192+
*Read The Docs* has [automation rules](https://docs.readthedocs.io/en/stable/automation-rules.html).
193+
We have one set up that will automatically build documentation for any semver tagged version of the project.
194+
195+
We need to pass the force flag `-f` to overwrite `modules.rst`, as otherwise Sphinx will skip over searching the `evasdk` directory.
196+
197+
To generate a local version of the documentation:
198+
```bash
199+
cd docs
200+
make html
201+
```
202+
203+
Then open the file `docs/_build/html/index.html` in your browser.
204+
177205
## License
178206

179207
This code is free to use under the terms of the Apache 2 license. Please refer to LICENSE for more information.

‎docs/Makefile

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
api_docs:
12+
sphinx-apidoc -f -o . .. ../setup.py
13+
14+
# Put it first so that "make" without argument is like "make help".
15+
help:
16+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
17+
18+
.PHONY: help Makefile
19+
20+
# Catch-all target: route all unknown targets to Sphinx using the new
21+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
22+
%: Makefile
23+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/conf.py

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
7+
# -- Path setup --------------------------------------------------------------
8+
9+
# If extensions (or modules to document with autodoc) are in another directory,
10+
# add these directories to sys.path here. If the directory is relative to the
11+
# documentation root, use os.path.abspath to make it absolute, like shown here.
12+
13+
import os
14+
import sys
15+
sys.path.insert(0, os.path.abspath('../'))
16+
17+
18+
# -- Project information -----------------------------------------------------
19+
20+
project = 'Eva Python SDK'
21+
copyright = '2021, Automata'
22+
author = 'Automata'
23+
24+
25+
# -- General configuration ---------------------------------------------------
26+
27+
# Add any Sphinx extension module names here, as strings. They can be
28+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
29+
# ones.
30+
extensions = [
31+
'sphinx.ext.autodoc',
32+
'm2r2',
33+
'sphinx.ext.autosectionlabel',
34+
]
35+
36+
# Add any paths that contain templates here, relative to this directory.
37+
templates_path = ['_templates']
38+
39+
# List of patterns, relative to source directory, that match files and
40+
# directories to ignore when looking for source files.
41+
# This pattern also affects html_static_path and html_extra_path.
42+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
43+
44+
45+
# -- Options for HTML output -------------------------------------------------
46+
47+
# The theme to use for HTML and HTML Help pages. See the documentation for
48+
# a list of builtin themes.
49+
#
50+
html_theme = 'alabaster'
51+
52+
53+
# Add any paths that contain custom static files (such as style sheets) here,
54+
# relative to this directory. They are copied after the builtin static files,
55+
# so a file named "default.css" will overwrite the builtin "default.css".
56+
html_static_path = ['_static']
57+
58+
59+
# Allows for Sphinx to pickup .md files alongside .rst files. This is useful for
60+
# including README.md to the Sphinx generated documentation.
61+
source_suffix = ['.rst', '.md']

‎docs/examples.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Examples
2+
========
3+
4+
This example shows usage of the Eva object, used for controlling Eva, reading Eva's current state and responding to different events triggered by Eva's operation.
5+
6+
.. literalinclude:: ../examples/eva_example.py
7+
8+
9+
This example shows usage of the eva_ws and eva_http modules, used for direct control using the network interfaces. eva_http also contains some helper functions not contained in the public API, such as lock_wait_for.
10+
11+
.. literalinclude:: ../examples/http_ws_example.py

‎docs/index.rst

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
.. Eva Python SDK documentation master file, created by
2+
sphinx-quickstart on Wed May 19 15:00:17 2021.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Eva Python SDK's documentation!
7+
===============================
8+
9+
Welcome to Eva Python SDK documentation.
10+
11+
Find the source code `here
12+
<https://github.com/automata-tech/eva_python_sdk>`_.
13+
14+
Below you will find up to date module documentation, examples of how to use the SDK, as well as a copy of the SDK's README.md which will outline installation details and much more.
15+
16+
17+
Contents
18+
========
19+
20+
.. toctree::
21+
:maxdepth: 2
22+
23+
Example Usage <examples>
24+
Module reference <modules>
25+
README.md <readme>
26+
27+
28+
Indices and tables
29+
==================
30+
31+
* :ref:`genindex`
32+
* :ref:`modindex`
33+
* :ref:`search`

‎docs/make.bat

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
13+
if "%1" == "" goto help
14+
15+
%SPHINXBUILD% >NUL 2>NUL
16+
if errorlevel 9009 (
17+
echo.
18+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
19+
echo.installed, then set the SPHINXBUILD environment variable to point
20+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
21+
echo.may add the Sphinx directory to PATH.
22+
echo.
23+
echo.If you don't have Sphinx installed, grab it from
24+
echo.http://sphinx-doc.org/
25+
exit /b 1
26+
)
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/modules.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
eva_python_sdk
2+
==============
3+
4+
.. toctree::
5+
:maxdepth: 4
6+
7+
evasdk

‎docs/readme.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
README.md
2+
==================
3+
4+
.. mdinclude:: ../README.md

0 commit comments

Comments
 (0)