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
changes/78/23578/3
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