15 files changed, 436 insertions, 0 deletions
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 00000000..d4bb2cbb
--- /dev/null
+++ b/docs/Makefile
@@ -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)
diff --git a/docs/api/dataset.md b/docs/api/dataset.md
new file mode 100644
index 00000000..168fa12a
--- /dev/null
+++ b/docs/api/dataset.md
@@ -0,0 +1,28 @@
+# Dataset package
+
+```{eval-rst}
+.. automodule:: sec_certs.dataset
+    :no-members:
+```
+
+This documentation doesn't provide full API reference for all members of `dataset` package. Instead, it concentrattes on the Dataset that are immediately exposed to the users. Namely, we focus on `CCDataset` and `FIPSDataset`.
+
+```{tip}
+The examples related to this package can be found at [common criteria notebook](./../notebooks/examples/common_criteria.ipynb) and [fips notebook](./../notebooks/examples/fips.ipynb).
+```
+
+## CCDataset
+
+```{eval-rst}
+.. currentmodule:: sec_certs.dataset
+.. autoclass:: CCDataset
+    :members:
+```
+
+## FIPSDataset
+
+```{eval-rst}
+.. currentmodule:: sec_certs.dataset
+.. autoclass:: FIPSDataset
+    :members:
+```
diff --git a/docs/api/model.md b/docs/api/model.md
new file mode 100644
index 00000000..406d24be
--- /dev/null
+++ b/docs/api/model.md
@@ -0,0 +1,42 @@
+# Model package
+
+```{eval-rst}
+.. automodule:: sec_certs.model
+    :no-members:
+```
+
+```{tip}
+The examples related to this package can be found at [model notebook](./../notebooks/examples/model.ipynb).
+```
+
+## CPEClassifier
+
+```{eval-rst}
+.. currentmodule:: sec_certs.model
+.. autoclass:: CPEClassifier
+    :members:
+```
+
+## SARTranformer
+
+```{eval-rst}
+.. currentmodule:: sec_certs.model
+.. autoclass:: SARTransformer
+    :members:
+```
+
+## DependencyFinder
+
+```{eval-rst}
+.. currentmodule:: sec_certs.model
+.. autoclass:: DependencyFinder
+    :members:
+```
+
+## DependencyVulnerabilityFinder
+
+```{eval-rst}
+.. currentmodule:: sec_certs.model
+.. autoclass:: DependencyVulnerabilityFinder
+    :members:
+```
+\ No newline at end of file
diff --git a/docs/api/sample.md b/docs/api/sample.md
new file mode 100644
index 00000000..4ff17be1
--- /dev/null
+++ b/docs/api/sample.md
@@ -0,0 +1,26 @@
+# Sample package
+
+```{eval-rst}
+.. automodule:: sec_certs.sample
+    :no-members:
+```
+
+```{tip}
+The examples related to this package can be found at [common criteria notebook](./../notebooks/examples/common_criteria.ipynb) and [fips notebook](./../notebooks/examples/fips.ipynb).
+```
+
+## CommonCriteriaCert
+
+```{eval-rst}
+.. currentmodule:: sec_certs.sample
+.. autoclass:: CommonCriteriaCert
+    :members:
+```
+
+## FIPSCertificate
+
+```{eval-rst}
+.. currentmodule:: sec_certs.sample
+.. autoclass:: FIPSCertificate
+    :members:
+```
+\ No newline at end of file
diff --git a/docs/code_of_conduct.md b/docs/code_of_conduct.md
new file mode 100644
index 00000000..74e5474b
--- /dev/null
+++ b/docs/code_of_conduct.md
@@ -0,0 +1,4 @@
+```{include} ../CODE_OF_CONDUCT.md
+:relative-docs: docs/
+:relative-images:
+```
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 00000000..d1a81b2f
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,73 @@
+# 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("."))
+from importlib.metadata import version as get_version
+
+# -- Project information -----------------------------------------------------
+
+project = "sec-certs"
+copyright = "2020-2022, Adam Janovsky, Petr Svenda, Jan Jancar, Jiri Michalik, Stanislav Bobon."
+# author = "Adam Janovsky, Petr Svenda, Jan Jancar, Jiri Michalik, Stanislav Bobon"
+
+# Note thas this inference won't work from Docker: https://github.com/pypa/setuptools_scm/#usage-from-docker
+release = ".".join(get_version("sec-certs").split(".")[:3])
+
+# -- 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 = ["myst_nb", "sphinx.ext.autodoc", "sphinx_design", "sphinx_copybutton"]
+
+# Don't exeute notbooks
+nb_execution_mode = "off"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# Don't show typehints in autodoc files
+autodoc_typehints = "none"
+
+# This is recommended by sphinx_design extension
+myst_enable_extensions = ["colon_fence"]
+
+# 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 = "sphinx_book_theme"
+
+# 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"]
+
+html_logo = "_static/logo.svg"
+html_favicon = "_static/logo_badge.svg"
+
+html_theme_options = {
+    "repository_url": "https://github.com/crocs-muni/sec-certs",
+    "repository_branch": "main",
+    "launch_buttons": {"binderhub_url": "https://mybinder.org"},
+    "use_fullscreen_button": False,
+}
+
+myst_heading_anchors = 3
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 00000000..93c926ba
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,26 @@
+---
+file_format: mystnb
+mystnb:
+  remove_code_source: true
+  execution_mode: 'force'
+---
+# Configuration
+
+The configuration is stored in yaml file `settings.yaml` at `sec_certs.config` package. Below are the supported options, descriptions and default values.
+
+
+```{code-cell} python
+from sec_certs.config import configuration
+from myst_nb import glue
+from IPython.display import Markdown
+
+cfg = configuration.config
+text = ""
+for key in cfg.__dict__:
+    text += f"`{key}`\n\n- Description: {cfg.get_desription(key)}\n"
+    text += f"- Default value: `{cfg.__getattribute__(key)}`\n\n"
+glue("text", Markdown(text))
+```
+```{glue:md} text
+:format: myst
+```
diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 100644
index 00000000..fc1b2138
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1,4 @@
+```{include} ../CONTRIBUTING.md
+:relative-docs: docs/
+:relative-images:
+```
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 00000000..4760ed1c
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,64 @@
+# Sec-certs documentation
+
+Welcome to the technical documentation of *sec-certs* tool for the data analysis of products certified with Common Criteria or FIPS 140 frameworks. If you're looking for general description of the tool, its use cases and capabilites, we refer you to [sec-certs homepage](https://seccerts.org/). If you are looking for more advanced knowledge, e.g. how to mine your own data, how to extend the tool, and so forth, this is the right place.
+
+There are three main parts of this documentation. *User's guide* describes high-level use of our tool. Driven by this knowledge, you can progress to *Notebook examples* that showcase some of the API that we use in the form of Jupyter notebooks. The documentation also contains some of the modules documented with `autodoc`, see *API reference*. Still, some dark corners of our codebase are not documented. To inspect the code directly, see the [sec_certs](https://github.com/crocs-muni/sec-certs/tree/main/sec_certs) module. If you want, you can run the notebooks as they are stored in the [project repository](https://github.com/crocs-muni/sec-certs/tree/main/notebooks). If you are interested in contributing to our project or in other aspects of our development, you can consult the relevant *GitHub artifacts*
+
+```{button-ref} quickstart
+:align: center
+:color: primary
+:ref-type: myst
+Show me Quickstart!
+```
+
+```{admonition} Launch notebooks in MyBinder
+Each of the notebooks can be launched interactively in MyBinder by clicking on 🚀 icon (top-right corner).
+```
+
+```{toctree}
+:hidden:
+:caption: Navigation
+:maxdepth: 1
+Seccerts homepage <https://seccerts.org/>
+Seccerts docs <https://seccerts.org/docs>
+GitHub repo <https://github.com/crocs-muni/sec-certs>
+Seccerts PyPi <https://pypi.org/project/sec-certs/>
+```
+
+```{toctree}
+:hidden: True
+:caption: User's guide
+:maxdepth: 1
+installation.md
+quickstart.md
+tutorial.md
+configuration.md
+```
+
+```{toctree}
+:caption: Notebook examples
+:hidden: True
+:maxdepth: 1
+notebooks/examples/common_criteria.ipynb
+notebooks/examples/fips.ipynb
+notebooks/examples/model.ipynb
+```
+
+```{toctree}
+:caption: API reference
+:hidden: True
+:maxdepth: 1
+api/sample.md
+api/dataset.md
+api/model.md
+```
+
+```{toctree}
+:maxdepth: 1
+:hidden: True
+:caption: GitHub artifacts
+readme.md
+contributing.md
+code_of_conduct.md
+license.md
+```
+\ No newline at end of file
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 00000000..71e685db
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,47 @@
+# Installation
+
+::::{tab-set}
+:::{tab-item} PyPi (pip)
+
+The tool can be installed from PyPi with
+
+```bash
+pip install -U sec-certs
+```
+
+Note, that `Python>=3.8` is required.
+
+:::
+
+:::{tab-item} Docker
+
+The tool can be pulled as a docker image with
+
+```bash
+docker pull seccerts/sec-certs
+```
+
+:::
+:::{tab-item} Build from sources
+
+The stable release is also published on [GitHub](https://github.com/crocs-muni/sec-certs/releases) from where it can be setup for development with
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install -e .
+```
+
+Alternatively, our Our [Dockerfile](https://github.com/crocs-muni/sec-certs/blob/main/Dockerfile) represents a reproducible way of setting up the environment.
+
+:::
+::::
+
+If you're not using Docker, you must install the dependencies as described below.
+
+## Dependencies
+
+- [Java](https://www.java.com/en) is needed to parse tables in FIPS pdf documents, must be available from `PATH`.
+- Some imported libraries have non-trivial dependencies to resolve:
+    - [pdftotext](https://github.com/jalan/pdftotext) requires [Poppler](https://poppler.freedesktop.org/) to be installed. We've experienced issues with older versions of Poppler (`0.x`), make sure to install `20.x` version of these libraries.
+    - [graphviz](https://pypi.org/project/graphviz/) requires `graphviz` to be on the path
+\ No newline at end of file
diff --git a/docs/license.md b/docs/license.md
new file mode 100644
index 00000000..4f6e8060
--- /dev/null
+++ b/docs/license.md
@@ -0,0 +1,6 @@
+# License
+
+```{include} ../LICENSE
+:relative-docs: docs/
+:relative-images:
+```
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 00000000..32bb2452
--- /dev/null
+++ b/docs/make.bat
@@ -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
+
+%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.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/notebooks b/docs/notebooks
new file mode 120000
index 00000000..7e2fa2a0
--- /dev/null
+++ b/docs/notebooks
@@ -0,0 +1 @@
+./../notebooks
+\ No newline at end of file
diff --git a/docs/quickstart.md b/docs/quickstart.md
new file mode 100644
index 00000000..e16a570d
--- /dev/null
+++ b/docs/quickstart.md
@@ -0,0 +1,56 @@
+# Quickstart
+
+::::{tab-set}
+
+:::{tab-item} Common Criteria
+1. Install the latest version with `pip install -U sec-certs` (see [installation](installation.md)).
+2. Use
+```python
+from sec_certs.dataset import CCDataset
+
+dset = CCDataset.from_web_latest()
+```
+to obtain to obtain freshly processed dataset from [seccerts.org](https://seccerts.org).
+
+3. Play with the dataset. See [example notebook](./notebooks/examples/common_criteria.ipynb).
+:::
+
+:::{tab-item} FIPS 140
+1. Install the latest version with `pip install -U sec-certs` (see [installation](installation.md)).
+2. Use
+```python
+from sec_certs.dataset import FIPSDataset
+
+dset = FIPSDataset.from_web_latest()
+```
+to obtain to obtain freshly processed dataset from [seccerts.org](https://seccerts.org).
+
+3. Play with the dataset. See [example notebook](./notebooks/examples/fips.ipynb).
+:::
+::::
+
+```{hint}
+You can work with those with the help of the [common criteria notebook](notebooks/examples/common_criteria.ipynb) or [fips notebook](notebooks/examples/fips.ipynb) and even launch them in MyBinder without installing anything. Just use the 🚀 icon (top-right corner).
+```
+
+If you insist on processing the whole certificates pipeline, make sure that you installed all [dependencies](installation.md#dependencies). Then, run
+
+::::{tab-set}
+:::{tab-item} Common Criteria
+```bash
+$ cc-certs all
+```
+:::
+
+:::{tab-item} FIPS 140
+```bash
+$ fips-certs new-run
+```
+:::
+::::
+
+This script takes a long time to run (few hours) and will create `./cc_dset` or `./fips_dset` directory. To see all options, call the entrypoint with `--help`.
+
+:::{hint}
+If you installed the docker image, use `docker run -it sec-certs bash` to run the container interactively.
+:::
diff --git a/docs/readme.md b/docs/readme.md
new file mode 100644
index 00000000..2cb706b3
--- /dev/null
+++ b/docs/readme.md
@@ -0,0 +1,4 @@
+```{include} ../README.md
+:relative-docs: docs/
+:relative-images:
+```