Skip to content

Commit 1fda1c8

Browse files
greenrobotgreenrobot
committed
Merge branch '52-sphinx' into dev
2 parents 366f5f2 + 654f134 commit 1fda1c8

28 files changed

+531
-49
lines changed

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,4 +34,5 @@ share/python-wheels/
3434
*.egg
3535
MANIFEST
3636
**/__pycache__
37-
env/
37+
env/
38+
doc/_build

‎doc/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)

‎doc/README.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
Building a Reference API
2+
========================
3+
4+
Setup
5+
-----
6+
7+
```
8+
./setup.sh
9+
```
10+
11+
Build
12+
-----
13+
14+
```
15+
source .venv/bin/activate
16+
make html
17+
```
18+

‎doc/_static/logo-white-500px.png‎

4.78 KB
Loading

‎doc/conf.py‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
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 = 'ObjectBox Python API'
10+
copyright = '2024, ObjectBox Ltd.'
11+
author = 'ObjectBox Ltd.'
12+
release = '4.0.0'
13+
14+
# -- General configuration ---------------------------------------------------
15+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
16+
17+
extensions = [
18+
'sphinx.ext.autodoc',
19+
'autoapi.extension',
20+
]
21+
# 'sphinx.ext.inheritance_diagram',
22+
# 'sphinx.ext.autodoc',
23+
24+
# -- autoapi configuration ---------------------------------------------------
25+
# https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html
26+
27+
autoapi_dirs = ['../objectbox']
28+
# autoapi_template_dir = ''
29+
# autoapi_file_patterns = ['*.py', '*.pyi']
30+
# autoapi_generate_api_docs = True
31+
autoapi_options = [
32+
'members',
33+
'inherited-members',
34+
'undoc-members',
35+
# 'private-members',
36+
# 'special-members',
37+
# 'show-inheritance',
38+
# 'show-inheritance-diagram',
39+
'show-module-summary',
40+
'imported-members',
41+
]
42+
# autoapi_ignore = ['*migrations']
43+
# autoapi_root = 'autoapi'
44+
autoapi_add_toctree_entry = False # default: True
45+
autoapi_python_class_content = "both" # default: "class"
46+
# autoapi_member_order = 'bysource'
47+
# autoapi_python_use_implicit_namespaces = False
48+
# autoapi_own_page_level = 'module'
49+
50+
# Advanced:
51+
# autoapi_keep_files = False
52+
53+
# Experimental:
54+
autodoc_typehints = 'description'
55+
56+
only_top_level : bool = True
57+
58+
if only_top_level:
59+
def skip_submodules(app, what, name, obj, skip, options):
60+
if what == "module":
61+
skip = True
62+
elif what == "package" and name != "objectbox":
63+
skip = True
64+
return skip
65+
66+
67+
def setup(sphinx):
68+
sphinx.connect("autoapi-skip-member", skip_submodules)
69+
70+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.venv']
71+
72+
# -- Options for HTML output -------------------------------------------------
73+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
74+
75+
html_theme = 'sphinx_rtd_theme'
76+
77+
html_static_path = ['_static']
78+
html_logo = '_static/logo-white-500px.png'

‎doc/index.rst‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
ObjectBox Python API
2+
====================
3+
4+
.. toctree::
5+
:maxdepth: 1
6+
:caption: Contents:
7+
8+
overview
9+
API Reference <autoapi/objectbox/index>
10+
ObjectBox Homepage <https://objectbox.io>
11+
ObjectBox Docs <https://docs.objectbox.io>
12+
GitHub <https://github.com/objectbox/objectbox-python>
13+
14+
15+
Further links
16+
=============
17+
18+
* Docs for Python, Java/Kotlin and Dart/Flutter: https://docs.objectbox.io
19+
* General Information: https://objectbox.io
20+
21+
Indices and tables
22+
==================
23+
24+
* :ref:`genindex`
25+
* :ref:`modindex`
26+
* :ref:`search`

‎doc/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+
%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

‎doc/overview.rst‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
API Overview
2+
============
3+
4+
This gives an overview of the ObjectBox Python API by showing most important parts to get started.
5+
6+
For beginners, we recommend our `Python database docs <https://docs.objectbox.io/>`_ at for more details;
7+
especially the `Getting Started <https://docs.objectbox.io/getting-started>`_ guide.
8+
This covers more than just the obligatory ``pip install --upgrade objectbox``.
9+
10+
.. currentmodule:: objectbox
11+
12+
Defining the Data Model
13+
-----------------------
14+
15+
The ``@Entity`` decorator is used to define a class as an ObjectBox entity.
16+
17+
.. autosummary::
18+
:nosignatures:
19+
20+
Entity
21+
22+
Each entity class defines a set of properties. The following property types are most commonly used:
23+
24+
.. autosummary::
25+
:nosignatures:
26+
27+
Id
28+
String
29+
Int32
30+
Int64
31+
Float32
32+
Float64
33+
Date
34+
Float32Vector
35+
36+
Note: ``Float32Vector`` is used for `on-device vector search <https://docs.objectbox.io/on-device-vector-search>`_.
37+
38+
Classes
39+
-------
40+
41+
Now, with the data model defined, you can start using the ObjectBox database.
42+
These are the main classes to interact with:
43+
44+
.. autosummary::
45+
:nosignatures:
46+
47+
Store
48+
Box
49+
Query
50+
51+
What's next
52+
-----------
53+
54+
* `Python database docs (docs.objectbox.io) <https://docs.objectbox.io/>`_
55+
* API reference (next in this API documentation)

‎doc/requirements.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
sphinx
2+
sphinx-rtd-theme
3+
sphinx-autoapi

‎doc/setup.sh‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
python3 -m venv .venv
2+
source .venv/bin/activate
3+
pip install -r requirements.txt
4+
pip install -r ../requirements.txt

0 commit comments

Comments
 (0)