Skip to content

Commit 6619291

Browse files
author
Verweijen
committed
Add documentation
1 parent 80f4f2a commit 6619291

21 files changed

+327
-7
lines changed

‎.github/workflows/sphinx.yml

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
name: "Sphinx: Render docs"
2+
3+
on: push
4+
5+
jobs:
6+
build:
7+
runs-on: ubuntu-latest
8+
permissions:
9+
contents: write
10+
id-token: write
11+
steps:
12+
- uses: actions/checkout@v4
13+
- name: Build HTML
14+
uses: ammaraskar/sphinx-action@dev
15+
- name: Upload artifacts
16+
uses: actions/upload-artifact@v4
17+
with:
18+
name: html-docs
19+
path: docs/build/html/
20+
- name: Deploy
21+
uses: peaceiris/actions-gh-pages@v3
22+
if: github.ref == 'refs/heads/package'
23+
with:
24+
github_token: ${{ secrets.GITHUB_TOKEN }}
25+
publish_dir: docs/build/html

‎docs/Makefile

+20
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

+35
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+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
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/source/api.rst

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
API
2+
===
3+
4+
InputData
5+
---------
6+
.. automodule:: piargus.inputdata
7+
:members: InputData, MetaData, MicroData, TableData, CodeList
8+
:show-inheritance:
9+
10+
Hierarchies
11+
-----------
12+
.. automodule:: piargus.inputdata.hierarchy
13+
:members: Hierarchy, TreeHierarchy, FlatHierarchy, LevelHierarchy
14+
:show-inheritance:
15+
16+
Safety rule
17+
-----------
18+
.. automodule:: piargus
19+
:members: dominance_rule, percent_rule, frequency_rule, request_rule, zero_rule, missing_rule, weight_rule, manual_rule, p_rule, nk_rule,
20+
:show-inheritance:
21+
22+
Output
23+
------
24+
25+
.. automodule:: piargus
26+
:members: Table, Apriori, TreeRecode
27+
:show-inheritance:
28+
29+
Jobs
30+
----
31+
.. automodule:: piargus
32+
:members: Job, JobSetupError
33+
:show-inheritance:
34+
35+
Tau-Argus
36+
---------
37+
.. automodule:: piargus
38+
:members: TauArgus, BatchWriter
39+
:show-inheritance:

‎changes.md ‎docs/source/changes.md

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
# Changelog #
2+
13
## Version 1.0.0 ##
24

35
- Add alias `Node` for `TreeHierarchyNode`.

‎docs/source/conf.py

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
project = 'PiArgus'
10+
copyright = '2025, Laurent Verweijen'
11+
author = 'Laurent Verweijen'
12+
13+
# -- General configuration ---------------------------------------------------
14+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
15+
16+
extensions = [
17+
'sphinx.ext.autodoc',
18+
'sphinx.ext.autosummary',
19+
'sphinx.ext.githubpages',
20+
'sphinx.ext.viewcode',
21+
'myst_parser',
22+
]
23+
24+
templates_path = ['_templates']
25+
exclude_patterns = []
26+
27+
28+
29+
# -- Options for HTML output -------------------------------------------------
30+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
31+
32+
html_theme = 'sphinx_rtd_theme'
33+
html_static_path = ['_static']

‎docs/source/index.rst

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
.. PiArgus documentation master file, created by
2+
sphinx-quickstart on Tue Jan 7 13:41:10 2025.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Welcome to PiArgus' documentation!
7+
==================================
8+
9+
This package provides a python wrapper around `τ-ARGUS <https://research.cbs.nl/casc/tau.htm>`_, a program to protect statistical tables.
10+
This package takes care of generating all the required metadata and runs τ-ARGUS in the background to do the heavy work.
11+
12+
For this package to work, it is required to install τ-ARGUS locally first.
13+
It's also recommended to read the `TauArgus manual <https://research.cbs.nl/casc/Software/TauManualV4.1.pdf>`_ to understand some of the underlying concepts used in this package.
14+
15+
.. toctree::
16+
:maxdepth: 2
17+
:caption: Contents:
18+
19+
installation
20+
tutorial
21+
api
22+
changes
23+
24+
Indices and tables
25+
==================
26+
27+
* :ref:`genindex`
28+
* :ref:`modindex`
29+
* :ref:`search`

‎docs/source/installation.rst

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
Installation
2+
========================================
3+
4+
Download and install the latest version of `τ-ARGUS <https://github.com/sdcTools/tauargus/releases>`_.
5+
Make sure to setup the location of the program on your path.
6+
For example (powershell):
7+
8+
.. code-block:: powershell
9+
10+
$env:path += ";\Path\To\Folder\Containing\TauArgus\Program" # Please adapt locally to put your own path here
11+
12+
Use `pip <https://pip.pypa.io/en/stable/getting-started/>`_ to install piargus.
13+
14+
.. code-block:: powershell
15+
16+
pip install --upgrade piargus

‎tutorial.md ‎docs/source/tutorial.md

File renamed without changes.

‎pyproject.toml

+67-2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,68 @@
11
[build-system]
2-
requires = ["setuptools>=40.6.0"]
3-
build-backend = "setuptools.build_meta"
2+
requires = ["setuptools", "setuptools-scm"]
3+
build-backend = "setuptools.build_meta"
4+
5+
[project]
6+
name = "piargus"
7+
dynamic = ["version"]
8+
authors = [
9+
{name = "lverweijen", email = "lauwerund@gmail.com"}
10+
]
11+
description = "Python wrapper around TauArgus"
12+
readme = "README.md"
13+
requires-python = ">= 3.9"
14+
keywords = [
15+
"statistical-disclosure-control",
16+
"tau-argus",
17+
]
18+
classifiers = [
19+
"Intended Audience :: Developers",
20+
"Intended Audience :: Science/Research",
21+
"Operating System :: Microsoft :: Windows",
22+
"License :: OSI Approved :: Apache Software License",
23+
"Programming Language :: Python :: 3",
24+
"Programming Language :: Python :: 3.9",
25+
"Programming Language :: Python :: 3.10",
26+
"Programming Language :: Python :: 3.11",
27+
"Programming Language :: Python :: 3.12",
28+
"Programming Language :: Python :: 3.13",
29+
"Typing :: Typed",
30+
]
31+
license = {text = "Apache License 2.0"}
32+
dependencies = [
33+
"littletree>=0.6.2",
34+
"pandas>=1.5",
35+
]
36+
37+
[project.optional-dependencies]
38+
export = [
39+
"Pillow >= 5.0",
40+
"matplotlib >= 3.0",
41+
"svglib >= 1.5.0",
42+
]
43+
44+
[project.urls]
45+
Homepage = "https://github.com/lverweijen/piargus"
46+
Repository = "https://github.com/lverweijen/piargus"
47+
Issues = "https://github.com/lverweijen/piargus/issues"
48+
Changelog = "https://github.com/lverweijen/piargus/blob/main/changes.md"
49+
50+
[tool.ruff]
51+
line-length = 100
52+
indent-width = 4
53+
target-version = "py39"
54+
src = ["src"]
55+
56+
[tool.ruff.format]
57+
preview = true
58+
59+
[tool.setuptools_scm]
60+
61+
[dependency-groups]
62+
dev = [
63+
"ruff>=0.8.2",
64+
"sphinx-rtd-theme>=3.0.2",
65+
"sphinx>=7.4.7",
66+
"myst>=1.0.4",
67+
"myst-parser>=3.0.1",
68+
]

‎src/piargus/__init__.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
from .table.safetyrule import *
1010
from .tauargus import TauArgus
1111

12-
__version__ = "1.0.1"
12+
__version__ = "1.0.2"
1313

1414
__all__ = [
1515
"Apriori",

‎src/piargus/inputdata/codelist.py

+5-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,11 @@
44

55

66
class CodeList:
7-
"""Describe a codelist for use with TauArgus"""
7+
"""Describe a codelist for use with TauArgus.
8+
9+
It can be used to attach labels to code lists.
10+
It only has effect when running TauArgus interactively.
11+
"""
812

913
@classmethod
1014
def from_cdl(cls, file):

‎src/piargus/inputdata/hierarchy/flathierarchy.py

+5
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@
22

33

44
class FlatHierarchy(Hierarchy):
5+
"""
6+
Hierarchy where all nodes are the same level.
7+
8+
This is used as a default when no hierarchy is specified.
9+
"""
510
__slots__ = "total_code"
611

712
is_hierarchical = False

‎src/piargus/inputdata/inputdata.py

+1
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212

1313

1414
class InputData(metaclass=abc.ABCMeta):
15+
"""Abstract base class for a dataset that needs to be protected by Tau Argus."""
1516
def __init__(
1617
self,
1718
dataset,

‎src/piargus/inputdata/tabledata.py

+3
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,9 @@
1616

1717

1818
class TableData(InputData, Table):
19+
"""
20+
A TableData instance contains data that has already been aggregated.
21+
"""
1922
def __init__(
2023
self,
2124
dataset,

‎src/piargus/job.py

+4
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@
99

1010

1111
class Job:
12+
"""Representation a data protection task.
13+
14+
This task can be fed to the tau-argus program.
15+
"""
1216
def __init__(
1317
self,
1418
input_data: InputData,

‎src/piargus/table/apriori.py

+3
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@
33

44

55
class Apriori:
6+
"""
7+
Apriori can be used to mark cells as safe or to specify that cells should not be suppressed.
8+
"""
69
@classmethod
710
def from_hst(cls, file, separator=','):
811
"""Read from apriori-file (extension .hst)."""

0 commit comments

Comments
 (0)