Use sphinx for generating documentation

This adds sphinx based documentation generation.  For now,
this manily renders some introduction and the autodoc-genreated
class/method reference from the source code for our libraries.

Actual user-level documentation for pySim-{prog,shell,read} remains
to be added separately

Change-Id: I52603e93c2c129a9e79687da6c534fa56a40a649
This commit is contained in:
Harald Welte 2021-04-02 13:38:00 +02:00
parent ee3501fc62
commit 94e8735bd3
7 changed files with 258 additions and 0 deletions

20
docs/Makefile Normal file
View File

@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#
# 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
# 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)

57
docs/conf.py Normal file
View File

@ -0,0 +1,57 @@
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- 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('..'))
# -- Project information -----------------------------------------------------
project = 'pysim'
copyright = '2021, Sylvain Munaut, Harald Welte, Philipp Maier'
author = 'Sylvain Munaut, Harald Welte, Philipp Maier'
# -- General configuration ---------------------------------------------------
# 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.autosectionlabel",
"sphinx.ext.napoleon"
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# 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 = ['_build', 'Thumbs.db', '.DS_Store']
# -- 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'
# 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']
autoclass_content = 'both'

50
docs/index.rst Normal file
View File

@ -0,0 +1,50 @@
.. pysim documentation master file
Welcome to Osmocom pySim
========================
Introduction
------------
pySim is a python implementation of various software that helps you with
managing subscriber identity cards for cellular networks, so-called SIM
cards.
Many Osmocom (Open Source Mobile Communications) projects relate to operating
private / custom cellular networks, and provisioning SIM cards for said networks
is in many cases a requirement to operate such networks.
To make use of most of pySim's features, you will need a `programmable` SIM card,
i.e. a card where you are the owner/operator and have sufficient credentials (such
as the `ADM PIN`) in order to write to many if not most of the files on the card.
Such cards are, for example, available from sysmocom, a major contributor to pySim.
See https://www.sysmocom.de/products/lab/sysmousim/ for more details.
pySim supports classic GSM SIM cards as well as ETSI UICC with 3GPP USIM and ISIM
applications. It is easily extensible, so support for additional files, card
applications, etc. can be added easily by any python developer. We do encourage you
to submit your contributions to help this collaborative development project.
pySim consists of several parts:
* a python :ref:`library<pySim library>` containing plenty of objects and methods that can be used for
writing custom programs interfacing with SIM cards.
* the [new] :ref:`interactive pySim-shell command line program<pySim-shell>`
* the [legacy] :ref:`pySim-prog and pySim-read tools<Legacy tools>`
.. toctree::
:maxdepth: 2
:caption: Contents:
shell
legacy
library
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

2
docs/legacy.rst Normal file
View File

@ -0,0 +1,2 @@
Legacy tools
============

92
docs/library.rst Normal file
View File

@ -0,0 +1,92 @@
pySim library
=============
pySim filesystem abstraction
----------------------------
.. automodule:: pySim.filesystem
:members:
pySim commands abstraction
--------------------------
.. automodule:: pySim.commands
:members:
pySim Transport
---------------
The pySim.transport classes implement specific ways how to
communicate with a SIM card. A "transport" provides ways
to transceive APDUs with the card.
The most commonly used transport uses the PC/SC interface to
utilize a variety of smart card interfaces ("readers").
Transport base class
~~~~~~~~~~~~~~~~~~~~
.. automodule:: pySim.transport
:members:
calypso / OsmocomBB transport
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This allows the use of the SIM slot of an an OsmocomBB compatible phone with the TI Calypso chipset,
using the L1CTL interface to talk to the layer1.bin firmware on the phone.
.. automodule:: pySim.transport.calypso
:members:
AT-command Modem transport
~~~~~~~~~~~~~~~~~~~~~~~~~~
This transport uses AT commands of a cellular modem in order to get access to the SIM card inserted
in such a modem.
.. automodule:: pySim.transport.modem_atcmd
:members:
PC/SC transport
~~~~~~~~~~~~~~~
PC/SC is the standard API for accessing smart card interfaces
on all major operating systems, including the MS Windows Family,
OS X as well as Linux / Unix OSs.
.. automodule:: pySim.transport.pcsc
:members:
Serial/UART transport
~~~~~~~~~~~~~~~~~~~~~
This transport implements interfacing smart cards via
very simplistic UART readers. These readers basically
wire together the Rx+Tx pins of a RS232 UART, provide
a fixed crystal oscilator for clock, and operate the UART
at 9600 bps. These readers are sometimes called `Phoenix`.
.. automodule:: pySim.transport.serial
:members:
pySim utility functions
-----------------------
.. automodule:: pySim.utils
:members:
pySim exceptions
----------------
.. automodule:: pySim.exceptions
:members:
pySim card_handler
------------------
.. automodule:: pySim.card_handler
:members:

35
docs/make.bat Normal file
View File

@ -0,0 +1,35 @@
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=.
set BUILDDIR=_build
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% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd

2
docs/shell.rst Normal file
View File

@ -0,0 +1,2 @@
pySim-shell
===========