Merge pull request #3 from sarnold/doc-updates

Add sphinx doc build/workflow

.github/workflows/ci.yml

@@ -45,7 +45,6 @@ jobs:
 
     - name: Run tests
       run: |
-        tox -e setup
         tox
       env:
         PLATFORM: ${{ matrix.os }}

.github/workflows/sphinx.yml

@@ -0,0 +1,48 @@
+name: Docs
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-20.04
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+
+    - uses: actions/setup-python@v2
+      with:
+        python-version: '3.9'
+
+    - name: Add python requirements
+      run: |
+        python -m pip install --upgrade pip
+        pip install tox
+
+    - name: Build docs
+      run: |
+        tox -e docs-lint
+        tox -e docs
+
+    - uses: actions/upload-artifact@v2
+      with:
+        name: ApiDocsHTML
+        path: "docs/_build/html/"
+
+    - name: set nojekyll for github
+      run: |
+        sudo touch docs/_build/html/.nojekyll
+
+    - name: Deploy docs to gh-pages
+      if: ${{ github.event_name == 'push' }}
+      uses: JamesIves/[email protected]
+      with:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        BRANCH: gh-pages
+        FOLDER: docs/_build/html/
+        SINGLE_COMMIT: true

.gitignore

@@ -78,6 +78,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/source/api/
 
 # PyBuilder
 target/

README.rst

@@ -1,27 +1,41 @@
 =========================================
- xmltoyml (and ymltoxml) for mavlink xml
+ ymltoxml (and xmltoyml) for mavlink xml
 =========================================
 
-Some scripts, and eventually a package, to convert real-world XML_ files
-to YAML_ and back again, preserving attributes and comments (with minor
-corrections).  The default file encoding for both types is UTF-8 without
-a Byte-Order Marker.
+|ci| |wheels| |release| |badge|
 
-Developer workflow
-==================
+|pylint|
+
+|tag| |license| |python|
+
+A Python command line tool to convert between XML_ files and YAML_ files,
+preserving attributes and comments (with minor corrections).  The default
+file encoding for both types is UTF-8 without a BOM.  The main intent is
+to support YAML-based development of custom mavlink_ dialects.
+
+Local workflow
+===============
 
 Tool requirements:
 
 * initially just recent Python and Tox_
 
 Both mavlink and pymavlink require a (host) GCC toolchain for full builds,
-however, the basic workflow to generate the library headers requires only
-Git, Python, and Tox.
+however, the basic workflow to generate mavlink library headers requires
+only Git, Python, and Tox.
 
+.. _mavlink: https://mavlink.io/en/messages/common.html
 .. _Tox: https://github.com/tox-dev/tox
 .. _XML: https://en.wikipedia.org/wiki/Extensible_Markup_Language
 .. _YAML: https://en.wikipedia.org/wiki/YAML
 
+.. note:: This project uses versioningit_ to generate and maintain the
+          version file, which only gets included in the sdist/wheel
+          packages. In a fresh clone, running any of the tox_ commands
+          should generate the current version file.
+
+.. _versioningit: https://github.com/jwodder/versioningit
+
 
 In-repo workflow with Tox
 -------------------------
@@ -34,7 +48,7 @@ package manager, eg::
   $ sudo apt-get install tox
 
 
-After cloning the repository, you can run the repo checks with the
+After cloning this repository, you can run the repo checks with the
 ``tox`` command.  It will build a virtual python environment with
 all the dependencies and run the specified commands, eg:
 
@@ -44,10 +58,10 @@ all the dependencies and run the specified commands, eg:
   $ cd ymltoxml/
   $ tox -e py
 
-There is no package yet, just some prototype scripts and a quick test
-against one of the mavlink dialect files. The above will run the round-trip
-test command using the your (default) system Python; to specify the Python
-version and host OS type, run something like::
+There are no actual unittests yet, but the above will run the base ``tox``
+command against one of the mavlink dialect files. Note this will run the
+round-trip test command using the your (default) system Python; to specify
+the Python version and host OS type, run something like::
 
   $ tox -e py39-linux
 
@@ -59,3 +73,40 @@ Full list of additional ``tox`` commands:
 * ``tox -e isort`` will run isort import checks
 * ``tox -e clean`` will remove temporary test files
 
+To build/lint the api docs, use the following tox commands:
+
+* ``tox -e docs`` build the documentation using sphinx and the api-doc plugin
+* ``tox -e docs-lint`` build the docs and run the sphinx link checking
+
+
+.. |ci| image:: https://github.com/sarnold/ymltoxml/actions/workflows/ci.yml/badge.svg
+    :target: https://github.com/sarnold/ymltoxml/actions/workflows/ci.yml
+    :alt: CI Status
+
+.. |wheels| image:: https://github.com/sarnold/ymltoxml/actions/workflows/wheels.yml/badge.svg
+    :target: https://github.com/sarnold/ymltoxml/actions/workflows/wheels.yml
+    :alt: Wheel Status
+
+.. |badge| image:: https://github.com/sarnold/ymltoxml/actions/workflows/pylint.yml/badge.svg
+    :target: https://github.com/sarnold/ymltoxml/actions/workflows/pylint.yml
+    :alt: Pylint Status
+
+.. |release| image:: https://github.com/sarnold/ymltoxml/actions/workflows/release.yml/badge.svg
+    :target: https://github.com/sarnold/ymltoxml/actions/workflows/release.yml
+    :alt: Release Status
+
+.. |pylint| image:: https://raw.githubusercontent.com/sarnold/ymltoxml/badges/main/pylint-score.svg
+    :target: https://github.com/sarnold/ymltoxml/actions/workflows/pylint.yml
+    :alt: Pylint score
+
+.. |license| image:: https://img.shields.io/github/license/sarnold/ymltoxml
+    :target: https://github.com/sarnold/ymltoxml/blob/master/LICENSE
+    :alt: License
+
+.. |tag| image:: https://img.shields.io/github/v/tag/sarnold/ymltoxml?color=green&include_prereleases&label=latest%20release
+    :target: https://github.com/sarnold/ymltoxml/releases
+    :alt: GitHub tag
+
+.. |python| image:: https://img.shields.io/badge/python-3.6+-blue.svg
+    :target: https://www.python.org/downloads/
+    :alt: Python

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SPHINXPROJ    = MAVConn
+SOURCEDIR     = source
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+set SPHINXPROJ=MAVConn
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/source/README.rst

@@ -0,0 +1 @@
+../../README.rst