Skip to content

Commit 46ebbbe

Browse files
Teque5Teque5
committed
basic documentation autodoc
1 parent 82af7fd commit 46ebbbe

File tree

10 files changed

+223
-12
lines changed

10 files changed

+223
-12
lines changed

‎.github/workflows/main.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ jobs:
2222
- name: Install dependencies
2323
run: |
2424
python -m pip install --upgrade pip
25-
pip install .[test,apps]
25+
pip install .[all]
2626
- name: Test with pytest
2727
run: |
2828
coverage run

‎.gitignore

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
# temp files
2+
__pycache__/
23
*.swp
3-
*.pyc
4+
*.py[cod]
45
.cache
56

6-
# setuptools related
7-
dist/*
8-
build/*
9-
.eggs/*
7+
# packaging related
8+
dist/
9+
build/
10+
eggs/
11+
.eggs/
1012
SigMF.egg-info/*
1113

1214
# test related
@@ -16,3 +18,6 @@ SigMF.egg-info/*
1618
coverage.xml
1719
pytest.xml
1820
htmlcov/*
21+
22+
# docs related
23+
docs/_build/

‎.readthedocs.yaml

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,16 +10,16 @@ build:
1010
tools:
1111
python: "3.13"
1212

13-
# # Build documentation in the "docs/" directory with Sphinx
14-
# sphinx:
15-
# configuration: docs/conf.py
16-
1713
# declare the Python requirements required to build your documentation
1814
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
1915
python:
2016
install:
2117
- method: pip
2218
path: .
2319
extra_requirements:
24-
- test
25-
- apps
20+
- all
21+
- requirements: docs/requirements.txt
22+
23+
# Build documentation in the "docs/" directory with Sphinx
24+
sphinx:
25+
configuration: docs/source/conf.py

‎docs/Makefile

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
if "%1" == "" goto help
14+
15+
%SPHINXBUILD% >NUL 2>NUL
16+
if errorlevel 9009 (
17+
echo.
18+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
19+
echo.installed, then set the SPHINXBUILD environment variable to point
20+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
21+
echo.may add the Sphinx directory to PATH.
22+
echo.
23+
echo.If you don't have Sphinx installed, grab it from
24+
echo.http://sphinx-doc.org/
25+
exit /b 1
26+
)
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/requirements.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
sphinx==7.1.2
2+
sphinx-rtd-theme==1.3.0rc1

‎docs/source/api.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
API
2+
===
3+
4+
.. autosummary::
5+
:toctree: generated
6+
7+
sigmf

‎docs/source/conf.py

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Copyright: Multiple Authors
2+
#
3+
# This file is part of sigmf-python. https://github.com/sigmf/sigmf-python
4+
#
5+
# SPDX-License-Identifier: LGPL-3.0-or-later
6+
"""Configuration file for the Sphinx documentation builder."""
7+
8+
import datetime
9+
import re
10+
from pathlib import Path
11+
12+
# parse info from project files
13+
14+
root = Path(__file__).parent.parent.parent
15+
with open(root / "sigmf" / "__init__.py", "r") as handle:
16+
init = handle.read()
17+
toolversion = re.search(r'__version__\s*=\s*[\'"]([^\'"]*)[\'"]', init).group(1)
18+
specversion = re.search(r'__specification__\s*=\s*[\'"]([^\'"]*)[\'"]', init).group(1)
19+
print("DBUG", toolversion, specversion)
20+
21+
# -- Project information
22+
23+
project = "sigmf"
24+
author = "Multiple Authors"
25+
copyright = f"2017-{datetime.date.today().year}, {author}"
26+
27+
release = toolversion
28+
version = toolversion
29+
30+
# -- General configuration
31+
32+
extensions = [
33+
"sphinx.ext.duration",
34+
"sphinx.ext.doctest",
35+
"sphinx.ext.autodoc",
36+
"sphinx.ext.autosummary",
37+
"sphinx.ext.intersphinx",
38+
]
39+
40+
intersphinx_mapping = {
41+
"python": ("https://docs.python.org/3/", None),
42+
"sphinx": ("https://www.sphinx-doc.org/en/master/", None),
43+
}
44+
intersphinx_disabled_domains = ["std"]
45+
46+
templates_path = ["_templates"]
47+
48+
# -- Options for HTML output
49+
50+
html_theme = "sphinx_rtd_theme"
51+
52+
# -- Options for EPUB output
53+
epub_show_urls = "footnote"

‎docs/source/index.rst

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
Welcome to SigMF!
2+
=================
3+
4+
**sigmf** is a Python library for working with radio recordings as specified in the `SigMF <https://sigmf.org/>`_ standard.
5+
It offers a *simple* and *intuitive* API for python developers.
6+
7+
Check out the :doc:`usage` section for further information, including
8+
how to :ref:`installation` the project.
9+
10+
.. note::
11+
12+
This project is under active development.
13+
14+
Contents
15+
--------
16+
17+
.. toctree::
18+
19+
usage
20+
api

‎docs/source/usage.rst

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
Usage
2+
=====
3+
4+
.. _installation:
5+
6+
Installation
7+
------------
8+
9+
To install the latest PyPi release, install from pip:
10+
11+
.. code-block:: console
12+
13+
$ pip install sigmf
14+
15+
To install the latest git release, build from source:
16+
17+
.. code-block:: console
18+
19+
$ git clone https://github.com/sigmf/sigmf-python.git
20+
$ cd sigmf-python
21+
$ pip install .
22+
23+
Testing
24+
-------
25+
26+
Testing can be run locally:
27+
28+
.. code-block:: console
29+
30+
$ coverage run
31+
32+
Run coverage on multiple python versions:
33+
34+
.. code-block:: console
35+
36+
$ tox run
37+
38+
Other tools developers may want to use:
39+
40+
.. code-block:: console
41+
42+
$ pytest -rA tests/test_archive.py # test one file verbosely
43+
$ pylint sigmf tests # lint entire project
44+
$ black sigmf tests # autoformat entire project
45+
$ isort sigmf tests # format imports for entire project
46+
47+
Examples
48+
--------
49+
50+
Load a SigMF archive; read all samples & metadata
51+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
52+
53+
.. code-block:: python
54+
55+
import sigmf
56+
handle = sigmf.sigmffile.fromfile("example.sigmf")
57+
handle.read_samples() # returns all timeseries data
58+
handle.get_global_info() # returns 'global' dictionary
59+
handle.get_captures() # returns list of 'captures' dictionaries
60+
handle.get_annotations() # returns list of all annotations
61+
62+
Verify SigMF dataset integrity & compliance
63+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
64+
65+
.. code-block:: console
66+
67+
$ sigmf_validate example.sigmf
68+
69+
TODO: Insert more examples from `README.md`.

0 commit comments

Comments
 (0)