Skip to content

Commit 0435334

Browse files
authored
feat(docs): introduce C++ documentation (alibaba#126)
1 parent 36941e2 commit 0435334

54 files changed

Lines changed: 3894 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ FlameGraph
4848

4949
# Images
5050
*.svg
51+
!docs/source/_static/prefetch.svg
5152

5253
# Third party dependencies archives
5354
third_party/*.tar.gz

‎docs/.gitignore‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Licensed to the Apache Software Foundation (ASF) under one
2+
# or more contributor license agreements. See the NOTICE file
3+
# distributed with this work for additional information
4+
# regarding copyright ownership. The ASF licenses this file
5+
# to you under the Apache License, Version 2.0 (the
6+
# "License"); you may not use this file except in compliance
7+
# with the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing,
12+
# software distributed under the License is distributed on an
13+
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
# KIND, either express or implied. See the License for the
15+
# specific language governing permissions and limitations
16+
# under the License.
17+
18+
_build

‎docs/Makefile‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Licensed to the Apache Software Foundation (ASF) under one
2+
# or more contributor license agreements. See the NOTICE file
3+
# distributed with this work for additional information
4+
# regarding copyright ownership. The ASF licenses this file
5+
# to you under the Apache License, Version 2.0 (the
6+
# "License"); you may not use this file except in compliance
7+
# with the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing,
12+
# software distributed under the License is distributed on an
13+
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
# KIND, either express or implied. See the License for the
15+
# specific language governing permissions and limitations
16+
# under the License.
17+
18+
# Adapted from Apache Arrow
19+
# https://github.com/apache/arrow/blob/main/docs/Makefile
20+
21+
#
22+
# Makefile for Sphinx documentation
23+
24+
# You can set these variables from the command line, and also
25+
# from the environment for the first two.
26+
SPHINXOPTS = -j8
27+
SPHINXBUILD = sphinx-build
28+
SOURCEDIR = source
29+
BUILDDIR = _build
30+
31+
# Put it first so that "make" without argument is like "make help".
32+
help:
33+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
34+
35+
.PHONY: help Makefile
36+
37+
# Catch-all target: route all unknown targets to Sphinx using the new
38+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
39+
%: Makefile
40+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
41+
42+
.PHONY: html
43+
html:
44+
$(SPHINXBUILD) -b html $(SPHINXOPTS) source $(BUILDDIR)/html
45+
@echo
46+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

‎docs/code-style.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,21 @@ This document defines the coding conventions for the paimon-cpp project. All pul
3131

3232
---
3333

34+
## Integer Types
35+
36+
Use **fixed-width integer types** from `<cstdint>`. Do **not** use plain `int`, `long`, `short`, or `unsigned`.
37+
38+
| Use | Instead of |
39+
|-----|-----------|
40+
| `int8_t` / `uint8_t` | `char` (for numeric data) |
41+
| `int16_t` / `uint16_t` | `short` |
42+
| `int32_t` / `uint32_t` | `int` / `unsigned int` |
43+
| `int64_t` / `uint64_t` | `long` / `long long` |
44+
45+
**Exception**: Loop variables iterating over small, bounded ranges (e.g. `for (int32_t i = 0; i < n; ++i)`) must still use `int32_t`, not `int`.
46+
47+
---
48+
3449
## Formatting
3550

3651
Formatting is based on **Google C++ Style** with the following overrides (defined in `.clang-format`):

‎docs/make.bat‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
@rem Licensed to the Apache Software Foundation (ASF) under one
2+
@rem or more contributor license agreements. See the NOTICE file
3+
@rem distributed with this work for additional information
4+
@rem regarding copyright ownership. The ASF licenses this file
5+
@rem to you under the Apache License, Version 2.0 (the
6+
@rem "License"); you may not use this file except in compliance
7+
@rem with the License. You may obtain a copy of the License at
8+
@rem
9+
@rem http://www.apache.org/licenses/LICENSE-2.0
10+
@rem
11+
@rem Unless required by applicable law or agreed to in writing,
12+
@rem software distributed under the License is distributed on an
13+
@rem "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
@rem KIND, either express or implied. See the License for the
15+
@rem specific language governing permissions and limitations
16+
@rem under the License.
17+
18+
@rem Adapted from Apache Arrow
19+
@rem https://github.com/apache/arrow/blob/main/docs/make.bat
20+
21+
@ECHO OFF
22+
23+
pushd %~dp0
24+
25+
REM Command file for Sphinx documentation
26+
27+
if "%SPHINXBUILD%" == "" (
28+
set SPHINXBUILD=sphinx-build
29+
)
30+
set SOURCEDIR=.
31+
set BUILDDIR=_build
32+
33+
%SPHINXBUILD% >NUL 2>NUL
34+
if errorlevel 9009 (
35+
echo.
36+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
37+
echo.installed, then set the SPHINXBUILD environment variable to point
38+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
39+
echo.may add the Sphinx directory to PATH.
40+
echo.
41+
echo.If you don't have Sphinx installed, grab it from
42+
echo.https://www.sphinx-doc.org/
43+
exit /b 1
44+
)
45+
46+
if "%1" == "" goto help
47+
48+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
49+
goto end
50+
51+
:help
52+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
53+
54+
:end
55+
popd

‎docs/requirements.txt‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
#
2+
# Note: keep this file in sync with conda_env_sphinx.txt !
3+
#
4+
5+
breathe
6+
myst-parser[linkify]
7+
pydata-sphinx-theme~=0.16
8+
sphinx-autobuild
9+
sphinx-copybutton
10+
sphinx-design
11+
sphinx-lint
12+
sphinxcontrib-mermaid
13+
sphinx
302 KB
Loading

‎docs/source/_static/prefetch.svg‎

Lines changed: 4 additions & 0 deletions
Loading
177 KB
Loading
Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
/**
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
19+
20+
/* Adapted from Apache Arrow */
21+
/* https://github.com/apache/arrow/blob/main/docs/source/_static/theme_overrides.css */
22+
23+
/* Customizing with theme CSS variables */
24+
25+
:root {
26+
/* Make headings more bold */
27+
--pst-font-weight-heading: 600;
28+
}
29+
30+
/* Contributing landing page overview cards */
31+
32+
.contrib-card {
33+
border-radius: 0;
34+
padding: 30px 10px 20px 10px;
35+
margin: 10px 0px;
36+
}
37+
38+
.contrib-card p.card-text {
39+
margin: 0px;
40+
}
41+
42+
.contrib-card .sd-card-img-top {
43+
margin: 2px;
44+
height: 75px;
45+
background: none !important;
46+
}
47+
48+
.contrib-card .sd-card-title {
49+
color: var(--pst-color-primary);
50+
font-size: var(--pst-font-size-h3);
51+
padding: 1rem 0rem 0.5rem 0rem;
52+
}
53+
54+
.contrib-card .sd-card-footer {
55+
border: none;
56+
}
57+
58+
/* This is the bootstrap CSS style for "table-striped". Since the theme does
59+
not yet provide an easy way to configure this globally, it easier to simply
60+
include this snippet here than updating each table in all rst files to
61+
add ":class: table-striped" */
62+
63+
.table tbody tr:nth-of-type(odd) {
64+
background-color: rgba(0, 0, 0, 0.05);
65+
}
66+
67+
/* Improve the vertical spacing in the C++ API docs
68+
(ideally this should be upstreamed to the pydata-sphinx-theme */
69+
70+
dl.cpp dd p {
71+
margin-bottom: .4rem;
72+
}
73+
74+
dl.cpp.enumerator {
75+
margin-bottom: 0.2rem;
76+
}
77+
78+
p.breathe-sectiondef-title {
79+
margin-top: 1rem;
80+
}
81+
82+
/* Keep social icons arranged horizontally in sidebar */
83+
84+
.sidebar-header-items__end {
85+
flex-wrap: wrap;
86+
}

0 commit comments

Comments
 (0)