Skip to content

Commit 6d96f23

Browse files
aradiaradi
committed
Add sphinx docs, improve API usability
1 parent 54486aa commit 6d96f23

16 files changed

Lines changed: 439 additions & 112 deletions

‎README.rst‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,10 @@ as possible (in contrast to JSON) and is not indentation dependent (in contrast
1111
to YAML). It was developed originally as the input format for the scientific
1212
simulation tool (`DFTB+ <https://github.com/dftbplus/dftbplus>`_), but is
1313
of general purpose. Data stored in HSD can be easily mapped to a subset of JSON
14-
or XML andvica versa.
14+
or XML and vica versa.
15+
16+
Detailed `documentation <https://hsd-python.readthedocs.io/>`_ can be found on
17+
`Read the Docs <https://hsd-python.readthedocs.io/>`_.
1518

1619

1720
Installation

‎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 = .
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/api.rst‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
*****************
2+
API documentation
3+
*****************
4+
5+
.. testsetup::
6+
7+
import hsd
8+
9+
10+
High level routines
11+
===================
12+
13+
.. autofunction:: hsd.load
14+
15+
.. autofunction:: hsd.load_string
16+
17+
.. autofunction:: hsd.dump
18+
19+
.. autofunction:: hsd.dump_string
20+
21+
22+
23+
Lower level building blocks
24+
===========================
25+
26+
.. autoclass:: hsd.HsdParser
27+
:members:
28+
29+
.. autoclass:: hsd.HsdEventHandler
30+
:members:
31+
32+
.. autoclass:: hsd.HsdDictBuilder
33+
:members:

‎docs/conf.py‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
7+
# -- Path setup --------------------------------------------------------------
8+
9+
# If extensions (or modules to document with autodoc) are in another directory,
10+
# add these directories to sys.path here. If the directory is relative to the
11+
# documentation root, use os.path.abspath to make it absolute, like shown here.
12+
#
13+
import os
14+
import sys
15+
sys.path.insert(0, os.path.abspath('../src'))
16+
17+
# -- Project information -----------------------------------------------------
18+
19+
project = 'hsd-python'
20+
copyright = '2021, DFTB+ developers group'
21+
author = 'DFTB+ developers group'
22+
23+
# The full version, including alpha/beta/rc tags
24+
release = '0.1'
25+
26+
27+
# -- General configuration ---------------------------------------------------
28+
29+
# Add any Sphinx extension module names here, as strings. They can be
30+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
31+
# ones.
32+
extensions = [
33+
'sphinx.ext.autodoc',
34+
'sphinx.ext.doctest',
35+
'sphinx.ext.napoleon'
36+
]
37+
38+
autodoc_member_order = 'bysource'
39+
40+
# Add any paths that contain templates here, relative to this directory.
41+
templates_path = ['_templates']
42+
43+
# List of patterns, relative to source directory, that match files and
44+
# directories to ignore when looking for source files.
45+
# This pattern also affects html_static_path and html_extra_path.
46+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
47+
48+
49+
# -- Options for HTML output -------------------------------------------------
50+
51+
# The theme to use for HTML and HTML Help pages. See the documentation for
52+
# a list of builtin themes.
53+
#
54+
# html_theme = 'alabaster'
55+
html_theme = 'sphinx_rtd_theme'
56+
57+
# Add any paths that contain custom static files (such as style sheets) here,
58+
# relative to this directory. They are copied after the builtin static files,
59+
# so a file named "default.css" will overwrite the builtin "default.css".
60+
html_static_path = ['_static']

‎docs/index.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
.. hsd-python documentation master file, created by
2+
sphinx-quickstart on Mon Sep 13 11:38:29 2021.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
######################################
7+
Welcome to hsd-python's documentation!
8+
######################################
9+
10+
.. toctree::
11+
:maxdepth: 2
12+
:caption: Contents:
13+
14+
introduction
15+
api

‎docs/introduction.rst‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
************
2+
Introduction
3+
************
4+
5+
This package contains utilities to read and write files in the Human-friendly
6+
Structured Data (HSD) format.
7+
8+
The HSD-format is very similar to both JSON and YAML, but tries to minimize the
9+
effort for **humans** to read and write it. It ommits special characters as much
10+
as possible (in contrast to JSON) and is not indentation dependent (in contrast
11+
to YAML). It was developed originally as the input format for the scientific
12+
simulation tool (`DFTB+ <https://github.com/dftbplus/dftbplus>`_), but is
13+
of general purpose. Data stored in HSD can be easily mapped to a subset of JSON
14+
or XML and vica versa.
15+
16+
17+
Installation
18+
============
19+
20+
The package can be installed via conda-forge::
21+
22+
conda install hsd-python
23+
24+
Alternatively, the package can be downloaded and installed via pip into the
25+
active Python interpreter (preferably using a virtual python environment) by ::
26+
27+
pip install hsd
28+
29+
or into the user space issueing ::
30+
31+
pip install --user hsd
32+
33+
34+
Quick tutorial
35+
==============
36+
37+
A typical, self-explaining input written in HSD looks like ::
38+
39+
driver {
40+
conjugate_gradients {
41+
moved_atoms = 1 2 "7:19"
42+
max_steps = 100
43+
}
44+
}
45+
46+
hamiltonian {
47+
dftb {
48+
scc = yes
49+
scc_tolerance = 1e-10
50+
mixer {
51+
broyden {}
52+
}
53+
filling {
54+
fermi {
55+
# This is comment which will be ignored
56+
# Note the attribute (unit) of the field below
57+
temperature [kelvin] = 100
58+
}
59+
}
60+
k_points_and_weights {
61+
supercell_folding {
62+
2 0 0
63+
0 2 0
64+
0 0 2
65+
0.5 0.5 0.5
66+
}
67+
}
68+
}
69+
}
70+
71+
The above input can be parsed into a Python dictionary with::
72+
73+
import hsd
74+
hsdinput = hsd.load_file("test.hsd")
75+
76+
The dictionary ``hsdinput`` will then look as::
77+
78+
{
79+
"driver": {
80+
"conjugate_gradients" {
81+
"moved_atoms": [1, 2, "7:19"],
82+
"max_steps": 100
83+
}
84+
},
85+
"hamiltonian": {
86+
"dftb": {
87+
"scc": True,
88+
"scc_tolerance": 1e-10,
89+
"mixer": {
90+
"broyden": {}
91+
},
92+
"filling": {
93+
"fermi": {
94+
"temperature": 100,
95+
"temperature.attrib": "kelvin"
96+
}
97+
}
98+
"k_points_and_weights": {
99+
"supercell_folding": [
100+
[2, 0, 0],
101+
[0, 2, 0],
102+
[0, 0, 2],
103+
[0.5, 0.5, 0.5]
104+
]
105+
}
106+
}
107+
}
108+
}
109+
110+
Being a simple Python dictionary, it can be easily queried and manipulated in
111+
Python ::
112+
113+
hsdinput["driver"]["conjugate_gradients"]["max_steps"] = 200
114+
115+
and then stored again in HSD format ::
116+
117+
hsd.dump_file(hsdinput, "test2.hsd")
118+
119+
120+
License
121+
========
122+
123+
The hsd-python package is licensed under the `BSD 2-clause license <LICENSE>`_.

‎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=.
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.https://www.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

‎src/hsd/__init__.py‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,13 @@
11
#------------------------------------------------------------------------------#
2-
# hsd: package for manipulating HSD-formatted data #
3-
# Copyright (C) 2011 - 2020 DFTB+ developers group #
4-
# #
5-
# See the LICENSE file for terms of usage and distribution. #
2+
# hsd-python: package for manipulating HSD-formatted data in Python #
3+
# Copyright (C) 2011 - 2021 DFTB+ developers group #
4+
# Licensed under the BSD 2-clause license. #
65
#------------------------------------------------------------------------------#
76
#
87
"""
9-
Central module for the hsd package
8+
Toolbox for reading, writing and manipulating HSD-data.
109
"""
1110
from .dictbuilder import HsdDictBuilder
1211
from .eventhandler import HsdEventHandler
13-
from .io import load, load_string, load_file, dump, dump_string, dump_file
12+
from .io import load, load_string, dump, dump_string
1413
from .parser import HsdParser

‎src/hsd/common.py‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
#------------------------------------------------------------------------------#
2-
# hsd: package for manipulating HSD-formatted data #
3-
# Copyright (C) 2011 - 2020 DFTB+ developers group #
4-
# #
5-
# See the LICENSE file for terms of usage and distribution. #
2+
# hsd-python: package for manipulating HSD-formatted data in Python #
3+
# Copyright (C) 2011 - 2021 DFTB+ developers group #
4+
# Licensed under the BSD 2-clause license. #
65
#------------------------------------------------------------------------------#
76
#
87
"""

‎src/hsd/dictbuilder.py‎

Lines changed: 20 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
#------------------------------------------------------------------------------#
2-
# hsd: package for manipulating HSD-formatted data #
3-
# Copyright (C) 2011 - 2020 DFTB+ developers group #
4-
# #
5-
# See the LICENSE file for terms of usage and distribution. #
2+
# hsd-python: package for manipulating HSD-formatted data in Python #
3+
# Copyright (C) 2011 - 2021 DFTB+ developers group #
4+
# Licensed under the BSD 2-clause license. #
65
#------------------------------------------------------------------------------#
76
#
87
"""
@@ -26,12 +25,19 @@
2625

2726

2827
class HsdDictBuilder(HsdEventHandler):
29-
"""Deserializes HSD into nested dictionaries
30-
31-
Note: hsdattrib passed by the generating events are ignored.
28+
"""Specific HSD event handler, which builds a nested Python dictionary.
29+
30+
Args:
31+
flatten_data: Whether multiline data in the HSD input should be
32+
flattened into a single list. Othewise a list of lists is created,
33+
with one list for every line (default).
34+
include_hsd_attribs: Whether the HSD-attributes (processing related
35+
attributes, like original tag name, line information, etc.) should
36+
be stored.
3237
"""
3338

34-
def __init__(self, flatten_data=False, include_hsd_attribs=False):
39+
def __init__(self, flatten_data: bool = False,
40+
include_hsd_attribs: bool = False):
3541
super().__init__()
3642
self._hsddict = {}
3743
self._curblock = self._hsddict
@@ -41,6 +47,12 @@ def __init__(self, flatten_data=False, include_hsd_attribs=False):
4147
self._include_hsd_attribs = include_hsd_attribs
4248

4349

50+
@property
51+
def hsddict(self):
52+
"""The dictionary which has been built"""
53+
return self._hsddict
54+
55+
4456
def open_tag(self, tagname, attrib, hsdattrib):
4557
if attrib is not None:
4658
self._curblock[tagname + ATTRIB_SUFFIX] = attrib
@@ -72,12 +84,6 @@ def add_text(self, text):
7284
self._data = self._text_to_data(text)
7385

7486

75-
@property
76-
def hsddict(self):
77-
"""Returns the dictionary which has been built"""
78-
return self._hsddict
79-
80-
8187
def _text_to_data(self, txt):
8288
data = []
8389
for line in txt.split("\n"):

0 commit comments

Comments
 (0)