mirror of https://gerrit.osmocom.org/pysim
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: I52603e93c2c129a9e79687da6c534fa56a40a649changes/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