Docs: Refreshed documentation build infrastructure

- Updated documentation requirements
- Moved documentation commands to tox
- Updated Sphinx conf and makefiles to simplify
- Updated notebooks to run with Python 3 kernel

.github/workflows/build_and_test.yml

@@ -61,16 +61,16 @@ jobs:
 
       - name: Install Python dependencies
         run: |
-          python -m pip install --upgrade pip wheel
-          python -m pip install tox tox-gh-actions -r requirements.txt -r requirements-test.txt
+          python -m pip install --upgrade pip wheel tox tox-gh-actions 
+          python -m pip install -r requirements.txt -r requirements-test.txt
 
       - name: Run unit tests
         run: |
           tox
 
       - name: Build wheel artifact
         run: |
-          python setup.py bdist_wheel
+          python -m pip wheel -w dist/ .
 
       - name: Upload wheel artifact
         uses: actions/upload-artifact@v3
@@ -100,24 +100,24 @@ jobs:
 
       - name: Install Python dependencies
         run: |
-          python -m pip install --upgrade pip wheel
+          python -m pip install --upgrade pip wheel tox tox-gh-actions 
           python -m pip install -r requirements-docs.txt
 
       - name: Install the library
         run: |
-          python setup.py install
+          python -m pip install .
 
       - name: Pre-run documentation notebooks
         run: |
-          python setup.py notebooks
+          tox -e notebooks
 
-      - name: Build source artifact
+      - name: Build documentation
         run: |
-          python setup.py sdist
+          tox -e doc
 
-      - name: Build documentation
+      - name: Build source artifact
         run: |
-          python setup.py doc
+          python setup.py sdist
 
       - name: Upload source artifact
         uses: actions/upload-artifact@v3

.readthedocs.yml

@@ -3,7 +3,7 @@
 version: 2
 
 python:
-    version: 2.7
+    version: 3.10
     install:
         - method: pip
           path: .

README.md

@@ -1,7 +1,7 @@
 pysap - Python library for crafting SAP's network protocols packets
 ===================================================================
 
-[![Build and test pysap](https://github.com/OWASP/pysap/workflows/build_and_test.yml/badge.svg?branch=master-0.2)](https://github.com/OWASP/pysap/workflows/build_and_test.yml)
+[![Build and test pysap](https://github.com/OWASP/pysap/actions/workflows/build_and_test.yml/badge.svg?branch=master-0.2)](https://github.com/OWASP/pysap/actions/workflows/build_and_test.yml)
 [![Latest Version](https://img.shields.io/pypi/v/pysap.svg)](https://pypi.python.org/pypi/pysap/)
 [![Documentation Status](http://readthedocs.org/projects/pysap/badge/?version=latest)](http://pysap.readthedocs.io/en/latest/?badge=latest)
 

docs/Makefile

@@ -1,96 +1,20 @@
-# Makefile for Sphinx documentation
+# Minimal makefile for Sphinx documentation
 #
 
-# You can set these variables from the command line.
-SPHINXOPTS   ?=
-SPHINXBUILD  ?= sphinx-build
-PAPER        ?=
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 
-# Internal variables.
-PAPEROPT_a4     = -D latex_elements.papersize=a4
-PAPEROPT_letter = -D latex_elements.papersize=letter
-# $(O) is meant as a shortcut for $(SPHINXOPTS)
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(O) $(SOURCEDIR)
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(O) $(SOURCEDIR)
-
-.PHONY: help
+# Put it first so that "make" without argument is like "make help".
 help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html        to make standalone HTML files"
-	@echo "  dirhtml     to make HTML files named index.html in directories"
-	@echo "  singlehtml  to make a single large HTML file"
-	@echo "  pickle      to make pickle files"
-	@echo "  json        to make JSON files"
-	@echo "  htmlhelp    to make HTML files and an HTML help project"
-	@echo "  qthelp      to make HTML files and a qthelp project"
-	@echo "  applehelp   to make an Apple Help Book"
-	@echo "  devhelp     to make HTML files and a Devhelp project"
-	@echo "  epub        to make an epub"
-	@echo "  latex       to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf    to make LaTeX files and run them through pdflatex"
-	@echo "  latexpdfja  to make LaTeX files and run them through platex/dvipdfmx"
-	@echo "  lualatexpdf to make LaTeX files and run them through lualatex"
-	@echo "  xelatexpdf  to make LaTeX files and run them through xelatex"
-	@echo "  text        to make text files"
-	@echo "  man         to make manual pages"
-	@echo "  texinfo     to make Texinfo files"
-	@echo "  info        to make Texinfo files and run them through makeinfo"
-	@echo "  gettext     to make PO message catalogs"
-	@echo "  changes     to make an overview of all changed/added/deprecated items"
-	@echo "  xml         to make Docutils-native XML files"
-	@echo "  pseudoxml   to make pseudoxml-XML files for display purposes"
-	@echo "  linkcheck   to check all external links for integrity"
-	@echo "  doctest     to run all doctests embedded in the documentation (if enabled)"
-	@echo "  coverage    to run coverage check of the documentation (if enabled)"
-	@echo "  dummy       to check syntax errors of document sources"
-
-.PHONY: clean
-clean:
-	rm -rf $(BUILDDIR)/*
-
-.PHONY: latexpdf
-latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-.PHONY: latexpdfja
-latexpdfja:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through platex and dvipdfmx..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-.PHONY: lualatexpdf
-lualatexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through lualatex..."
-	$(MAKE) PDFLATEX=lualatex -C $(BUILDDIR)/latex all-pdf
-	@echo "lualatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-.PHONY: xelatexpdf
-xelatexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through xelatex..."
-	$(MAKE) PDFLATEX=xelatex -C $(BUILDDIR)/latex all-pdf
-	@echo "xelatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-.PHONY: info
-info:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo "Running Texinfo files through makeinfo..."
-	make -C $(BUILDDIR)/texinfo info
-	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: gettext
-gettext:
-	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+.PHONY: help Makefile
 
-# Catch-all target: route all unknown targets to Sphinx
-.PHONY: 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) -b "$@" $(ALLSPHINXOPTS) "$(BUILDDIR)/$@"
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -1,182 +1,42 @@
-# -*- coding: utf-8 -*-
-#
 # Configuration file for the Sphinx documentation builder.
 #
-# This file does only contain a selection of the most common options. For a
-# full list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
-
-import pysap
-
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-import os
-import sys
-sys.path.insert(0, os.path.abspath('..'))
-
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 # -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-
-project = u'pysap'
-author = u'Martin Gallo, OWASP CBAS Project'
-
-# The short X.Y version
+import pysap
 version = pysap.__version__
-# The full version, including alpha/beta/rc tags
 release = version
-
+project = 'pysap'
+copyright = 'Martin Gallo, OWASP CBAS Project'
+author = 'Martin Gallo, OWASP CBAS Project'
 
 # -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.viewcode',
-    'nbsphinx',
-    'sphinx.ext.mathjax',
-    'm2r',
+    "sphinxcontrib.apidoc",
+    "nbsphinx",
+    "m2r",
 ]
 
-# Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
+exclude_patterns = ['_build', '**.ipynb_checkpoints']
 
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
-source_suffix = ['.rst', '.md']
-
-# The master toctree document.
-master_doc = 'index'
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store', '**.ipynb_checkpoints']
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
 
 
 # -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
 html_theme = 'alabaster'
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
-# html_theme_options = {}
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
-#
-# The default sidebars (for documents that don't match any pattern) are
-# defined by theme itself.  Builtin themes are using these templates by
-# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
-# 'searchbox.html']``.
-#
-# html_sidebars = {}
-
-
-# -- Options for HTMLHelp output ---------------------------------------------
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'pysapdoc'
-
-
-# -- Options for LaTeX output ------------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (master_doc, 'pysap.tex', u'pysap Documentation',
-     author, 'manual'),
-]
-
-
-# -- Options for manual page output ------------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, project, u'pysap Documentation',
-     [author], 1)
-]
-
-
-# -- Options for Texinfo output ----------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (master_doc, project, u'pysap Documentation',
-     author, project, 'Python library for crafting SAP\'s network protocols packets',
-     'Miscellaneous'),
-]
-
-
-# Automatically build API docs
-def run_apidoc(_):
-    ignore_paths = []
-    argv = [
-        "-f",           # Force
-        "-T",           # No TOC
-        "-e",           # Each module on its own page
-        "-M",           # Module first
-        "-o", "api/",   # Output on "api/"
-        "../pysap"      # Only document pysap module
-    ] + ignore_paths
-
-    from sphinx.ext import apidoc
-    apidoc.main(argv)
-
 
-def setup(app):
-    app.connect('builder-inited', run_apidoc)
+# -- API Doc configuration
+apidoc_module_dir = "../pysap"
+apidoc_output_dir = "api/"
+apidoc_separate_modules = True
+apidoc_toc_file = False
+apidoc_module_first = True