mirror of https://gerrit.osmocom.org/pysim
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:
parent
ee3501fc62
commit
94e8735bd3
|
@ -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)
|
|
@ -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'
|
|
@ -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`
|
|
@ -0,0 +1,2 @@
|
||||||
|
Legacy tools
|
||||||
|
============
|
|
@ -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:
|
|
@ -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
|
|
@ -0,0 +1,2 @@
|
||||||
|
pySim-shell
|
||||||
|
===========
|
Loading…
Reference in New Issue