Skip to content

Commit 22328ac

Browse files
yl-1993yl-1993
authored
[Feature] Add readthedocs for Python (#8)
1 parent 5105b62 commit 22328ac

36 files changed

+684
-263
lines changed

‎.github/workflows/build.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ jobs:
4444
source /root/miniconda3/etc/profile.d/conda.sh && conda activate openxrlab
4545
pip install conan
4646
conan remote add openxrlab http://conan.openxrlab.org.cn/artifactory/api/conan/openxrlab
47-
cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release -DBUILD_EXTERNAL=ON -DENABLE_TEST=ON -DCODE_COVERAGE=ON
47+
cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release -DBUILD_EXTERNAL=OFF -DENABLE_TEST=ON -DCODE_COVERAGE=ON
4848
cmake --build build -j4 --target install
4949
- name: Prepare test data
5050
run: |

‎.readthedocs.yml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
version: 2
2+
3+
formats: all
4+
5+
python:
6+
version: 3.7
7+
install:
8+
- requirements: requirements/docs.txt
9+
- requirements: requirements/readthedocs.txt

‎LICENSE

Lines changed: 218 additions & 203 deletions
Large diffs are not rendered by default.

‎README.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,11 @@
22

33
<div align="left">
44

5+
[![Documentation](https://readthedocs.org/projects/xrprimer/badge/?version=latest)](https://xrprimer.readthedocs.io/en/latest/?badge=latest)
56
[![actions](https://github.com/openxrlab/xrprimer/workflows/build/badge.svg)](https://github.com/openxrlab/xrprimer/actions)
67
[![codecov](https://codecov.io/gh/openxrlab/xrprimer/branch/main/graph/badge.svg)](https://codecov.io/gh/openxrlab/xrprimer)
78
[![PyPI](https://img.shields.io/pypi/v/xrprimer)](https://pypi.org/project/xrprimer/)
8-
[![LICENSE](https://img.shields.io/github/license/openxrlab/xrprimer.svg)](https://github.com/openxrlab/xrprimer/blob/main/LICENSE)
9+
[![Percentage of issues still open](https://isitmaintained.com/badge/open/openxrlab/xrprimer.svg)](https://github.com/openxrlab/xrprimer/issues)
910

1011
</div>
1112

@@ -82,7 +83,8 @@ If you face some installation issues, you may first refer to this [Frequently As
8283

8384
## License
8485

85-
The license of our codebase is [Apache-2.0](LICENSE). Note that this license only applies to code in our library, the dependencies of which are separate and individually licensed. We would like to pay tribute to open-source implementations to which we rely on. Please be aware that using the content of dependencies may affect the license of our codebase.
86+
The license of our codebase is Apache-2.0. Note that this license only applies to code in our library, the dependencies of which are separate and individually licensed. We would like to pay tribute to open-source implementations to which we rely on. Please be aware that using the content of dependencies may affect the license of our codebase. Refer to [LICENSE](LICENSE) to view the full license.
87+
8688

8789
## Citation
8890

‎cpp/pybind/CMakeLists.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,3 +25,4 @@ target_include_directories(xrprimer_cpp PUBLIC
2525
$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/cpp/>
2626
$<INSTALL_INTERFACE:include/>
2727
)
28+
set_target_properties(xrprimer_cpp PROPERTIES LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)

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

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
xrprimer.data_structure
2+
-----------------------
3+
4+
camera
5+
^^^^^^
6+
.. automodule:: xrprimer.data_structure.camera
7+
:members:
8+
9+
10+
xrprimer.calibration
11+
--------------------
12+
13+
.. automodule:: xrprimer.calibration
14+
:members:
15+
16+
17+
xrprimer.ops
18+
------------
19+
20+
projection
21+
^^^^^^^^^^
22+
.. automodule:: xrprimer.ops.projection
23+
:members:
24+
25+
triangulation
26+
^^^^^^^^^^^^^
27+
.. automodule:: xrprimer.ops.triangulation
28+
:members:
29+
30+
31+
xrprimer.transform
32+
------------------
33+
34+
camera
35+
^^^^^^
36+
.. automodule:: xrprimer.transform.camera
37+
:members:
38+
39+
camera convention
40+
^^^^^^^^^^^^^^^^^
41+
.. automodule:: xrprimer.transform.convention.camera
42+
:members:
43+
44+
image
45+
^^^^^
46+
.. automodule:: xrprimer.transform.image
47+
:members:
48+
49+
50+
xrprimer.utils
51+
--------------
52+
.. automodule:: xrprimer.utils
53+
:members:

‎docs/en/changelog.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Changelog
2+
3+
### v0.6.0 (01/09/2022/)
4+
5+
**Highlights**
6+
7+
- Support iOS and Linux compilation
8+
- Support installation via pypi, ranging from python 3.6 to 3.10
9+
- Support various camera models (Pinhole, Fisheye, Omni etc.)
10+
- Support basic 3D operations (Triangulator, Projector etc.)
11+
- Support Multi-camera extrinsic calibration tools
12+
13+
**New Features**
14+
15+
- Add pybind to create Python bindings of C++ data structures and switch python backend to C++ code
16+
- Add camera convention convert method
17+
- Add camera calibrator in python to support 3 types of calibration
18+
- Add image class and support the conversion with OpenCV
19+
- Add external deps and use conan manager to accelerate the compilation
20+
- Provide samples to demonstrate linking XRPrimer in other C++ projects

‎docs/en/conf.py

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
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 re
15+
import sys
16+
17+
import sphinx_rtd_theme
18+
19+
sys.path.insert(0, os.path.abspath('../../python'))
20+
21+
# -- Project information -----------------------------------------------------
22+
23+
project = 'XRPrimer'
24+
copyright = '2022, OpenXRLab'
25+
author = 'XRPrimer Authors'
26+
version_file = '../../version.txt'
27+
28+
29+
def parse_version_from_file(filepath):
30+
"""Parse version txt into string and tuple.
31+
32+
Args:
33+
filepath (str): The version filepath.
34+
Returns:
35+
str: The version string, e.g., "0.4.0"
36+
dict: The version info, e.g.,
37+
{
38+
'XRPRIMER_VERSION_MAJOR': 0,
39+
'XRPRIMER_VERSION_MINOR': 4,
40+
'XRPRIMER_VERSION_PATCH': 0,
41+
}
42+
"""
43+
keywords = [
44+
'XRPRIMER_VERSION_MAJOR', 'XRPRIMER_VERSION_MINOR',
45+
'XRPRIMER_VERSION_PATCH'
46+
]
47+
version_info = {}
48+
version_list = []
49+
with open(filepath) as f:
50+
content = f.read()
51+
for keyword in keywords:
52+
regex = rf'{keyword}\s*([0-9]+)'
53+
obj = re.search(regex, content)
54+
vid = obj.group(1)
55+
version_list.append(vid)
56+
assert keyword not in version_info
57+
version_info[keyword] = int(vid)
58+
version = '.'.join(version_list)
59+
return version, version_info
60+
61+
62+
def get_version(version_file):
63+
version, _ = parse_version_from_file(version_file)
64+
return version
65+
66+
67+
# The full version, including alpha/beta/rc tags
68+
release = get_version(version_file)
69+
70+
# -- General configuration ---------------------------------------------------
71+
72+
# Add any Sphinx extension module names here, as strings. They can be
73+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
74+
# ones.
75+
extensions = [
76+
'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.viewcode',
77+
'sphinx_markdown_tables', 'sphinx_copybutton', 'myst_parser'
78+
]
79+
80+
autodoc_mock_imports = ['xrprimer_cpp']
81+
82+
# Parse `Returns` in docstr with parameter style
83+
napoleon_custom_sections = [('Returns', 'params_style')]
84+
85+
# Ignore >>> when copying code
86+
copybutton_prompt_text = r'>>> |\.\.\. '
87+
copybutton_prompt_is_regexp = True
88+
89+
# Add any paths that contain templates here, relative to this directory.
90+
templates_path = ['_templates']
91+
92+
# The suffix(es) of source filenames.
93+
# You can specify multiple suffix as a list of string:
94+
#
95+
source_suffix = {
96+
'.rst': 'restructuredtext',
97+
'.md': 'markdown',
98+
}
99+
100+
# List of patterns, relative to source directory, that match files and
101+
# directories to ignore when looking for source files.
102+
# This pattern also affects html_static_path and html_extra_path.
103+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
104+
105+
# -- Options for HTML output -------------------------------------------------
106+
107+
# The theme to use for HTML and HTML Help pages. See the documentation for
108+
# a list of builtin themes.
109+
#
110+
html_theme = 'sphinx_rtd_theme'
111+
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
112+
113+
# Enable ::: for my_st
114+
myst_enable_extensions = ['colon_fence']
115+
116+
master_doc = 'index'

‎docs/en/index.rst

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
Welcome to XRPrimer's documentation!
2+
=======================================
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
:caption: Installation
7+
8+
installation/cpp.md
9+
installation/python.md
10+
11+
.. toctree::
12+
:maxdepth: 2
13+
:caption: Data Structure
14+
15+
data_structure/camera.md
16+
data_structure/image.md
17+
data_structure/pose.md
18+
19+
.. toctree::
20+
:maxdepth: 2
21+
:caption: Operations
22+
23+
ops/triangulator.md
24+
ops/projector.md
25+
26+
.. toctree::
27+
:maxdepth: 2
28+
:caption: Transform
29+
30+
transform/camera_convention.md
31+
32+
.. toctree::
33+
:maxdepth: 2
34+
:caption: Tools
35+
36+
tools/calibrate_multiple_cameras.md
37+
38+
.. toctree::
39+
:maxdepth: 2
40+
:caption: Unit tests
41+
42+
test.md
43+
44+
.. toctree::
45+
:maxdepth: 2
46+
:caption: Notes
47+
48+
faq.md
49+
changelog.md
50+
51+
.. toctree::
52+
:maxdepth: 2
53+
:caption: License
54+
55+
license.rst
56+
57+
.. toctree::
58+
:maxdepth: 1
59+
:caption: API Reference
60+
61+
api.rst
62+
63+
Indices and tables
64+
==================
65+
66+
* :ref:`genindex`
67+
* :ref:`search`

‎docs/en/installation/cpp.md

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@
1313
+ C++14 or later compiler
1414
+ GCC 7.5+
1515
+ CMake 3.15+
16+
+ LAPACK & BLAS
17+
1. If using conda, `conda install -c conda-forge lapack`
18+
2. If sudo is available, `apt update & apt -y install libatlas-base-dev`
1619

1720
Optional:
1821
+ [Conan](https://docs.conan.io/en/1.46/installation.html) (for using pre-built 3rd-party libraries)
@@ -70,9 +73,10 @@ Refer to [build_ios.sh](../../../scripts/build_ios.sh) for more details.
7073
CPP library
7174

7275
```bash
73-
# compile
76+
# compile (Skip the following two lines if it has been compiled)
7477
cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release -DENABLE_TEST=ON
7578
cmake --build build -j4
79+
7680
# run test
7781
cd build
7882
wget -q https://openxrlab-share.oss-cn-hongkong.aliyuncs.com/xrprimer/xrprimer.tar.gz && tar -xzf xrprimer.tar.gz && rm xrprimer.tar.gz
@@ -83,11 +87,14 @@ ln -sfn xrprimer/test test
8387
Python library
8488

8589
```bash
86-
cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release
90+
# compile (Skip the following two lines if it has been compiled)
91+
cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release -DENABLE_TEST=ON
8792
cmake --build build -j4
93+
94+
# run test
8895
cd build
8996
wget -q https://openxrlab-share.oss-cn-hongkong.aliyuncs.com/xrprimer/xrprimer.tar.gz && tar -xzf xrprimer.tar.gz && rm xrprimer.tar.gz
90-
PYTHONPATH=./cpp/pybind/ python ../cpp/tests/test_multi_camera_calibrator.py
97+
PYTHONPATH=./lib/ python ../cpp/tests/test_multi_camera_calibrator.py
9198
```
9299

93100
### How to link in C++ projects

‎docs/en/license.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
LICENSE
2+
-------
3+
4+
.. include:: ../../LICENSE

0 commit comments

Comments
 (0)