Skip to content

Commit 37e38d2

Browse files
SylvainCorlaySylvainCorlay
committed
Minimal breathe documentation
1 parent 834f48c commit 37e38d2

14 files changed

+833
-21
lines changed

‎.gitignore

Lines changed: 43 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,50 @@
1-
# Python Artefacts
1+
# Prerequisites
2+
*.d
23

3-
*.py[cod]
4+
# Compiled Object files
5+
*.slo
6+
*.lo
7+
*.o
8+
*.obj
49

5-
# C extensions
10+
# Precompiled Headers
11+
*.gch
12+
*.pch
613

14+
# Compiled Dynamic libraries
715
*.so
16+
*.dylib
17+
*.dll
818

9-
# Packages
10-
11-
*.egg
12-
*.egg-info
13-
dist
14-
build
15-
eggs
16-
parts
17-
bin
18-
var
19-
sdist
20-
develop-eggs
21-
.installed.cfg
22-
lib
23-
lib64
24-
__pycache__
25-
tmp/
19+
# Compiled Static libraries
20+
*.lai
21+
*.la
22+
*.a
23+
*.lib
24+
25+
# Executables
26+
*.exe
27+
*.out
28+
*.app
29+
30+
# Vim tmp files
31+
*.swp
32+
33+
# Test build artefacts
34+
test/test_xtensor
35+
test/CMakeCache.txt
36+
test/Makefile
37+
test/CMakeFiles/
38+
test/cmake_install.cmake
2639

27-
# Jupyter Artefacts
40+
# Documentation build artefacts
41+
docs/CMakeCache.txt
42+
docs/xml/
43+
docs/build/
44+
45+
# Jupyter artefacts
2846
.ipynb_checkpoints/
47+
48+
# Python
49+
*.py[cod]
50+
__pycache__

‎README.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
[![Travis](https://travis-ci.org/QuantStack/xtensor.svg?branch=master)](https://travis-ci.org/QuantStack/xtensor-python)
44
[![Appveyor](https://ci.appveyor.com/api/projects/status/qx61nsg4ebxnj8s9?svg=true)](https://ci.appveyor.com/project/QuantStack/xtensor-python)
5+
[![Documentation](http://readthedocs.org/projects/xtensor-python/badge/?version=latest)](https://xtensor-python.readthedocs.io/en/latest/?badge=latest)
56

67
Python bindings for the [xtensor](https://github.com/QuantStack/xtensor) C++ multi-dimensional array library.
78

@@ -141,6 +142,34 @@ Testing `xtensor-python` requires `pytest`
141142

142143
To pick up changes in `xtensor-python` while rebuilding, delete the `build/` directory.
143144

145+
## Building the HTML Documentation
146+
147+
`xtensor-python`'s documentation is built with three tools
148+
149+
- [doxygen](http://www.doxygen.org)
150+
- [sphinx](http://www.sphinx-doc.org)
151+
- [breathe](https://breathe.readthedocs.io)
152+
153+
While doxygen must be installed separately, you can install breathe by typing
154+
155+
```bash
156+
pip install breathe
157+
```
158+
159+
Breathe can also be installed with `conda`
160+
161+
```bash
162+
conda install -c conda-forge breathe
163+
```
164+
165+
Finally, build the documentation with
166+
167+
```bash
168+
make html
169+
```
170+
171+
from the `docs` subdirectory.
172+
144173
## License
145174

146175
We use a shared copyright model that enables all contributors to maintain the

‎docs/Doxyfile

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
PROJECT_NAME = "xtensor-python"
2+
XML_OUTPUT = xml
3+
INPUT = ../include
4+
GENERATE_LATEX = NO
5+
GENERATE_MAN = NO
6+
GENERATE_RTF = NO
7+
CASE_SENSE_NAMES = NO
8+
GENERATE_HTML = NO
9+
GENERATE_XML = YES
10+
RECURSIVE = YES
11+
QUIET = YES
12+
JAVADOC_AUTOBRIEF = YES

‎docs/Makefile

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# You can set these variables from the command line.
2+
SPHINXOPTS =
3+
SPHINXBUILD = sphinx-build
4+
PAPER =
5+
BUILDDIR = build
6+
7+
# User-friendly check for sphinx-build
8+
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
9+
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
10+
endif
11+
12+
# Internal variables.
13+
PAPEROPT_a4 = -D latex_paper_size=a4
14+
PAPEROPT_letter = -D latex_paper_size=letter
15+
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
16+
# the i18n builder cannot share the environment and doctrees with the others
17+
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
18+
19+
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext api
20+
21+
default: html
22+
23+
help:
24+
@echo "Please use \`make <target>' where <target> is one of"
25+
@echo " html to make standalone HTML files"
26+
@echo " dirhtml to make HTML files named index.html in directories"
27+
@echo " singlehtml to make a single large HTML file"
28+
@echo " pickle to make pickle files"
29+
@echo " json to make JSON files"
30+
@echo " htmlhelp to make HTML files and a HTML help project"
31+
@echo " qthelp to make HTML files and a qthelp project"
32+
@echo " applehelp to make an Apple Help Book"
33+
@echo " devhelp to make HTML files and a Devhelp project"
34+
@echo " epub to make an epub"
35+
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
36+
@echo " latexpdf to make LaTeX files and run them through pdflatex"
37+
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
38+
@echo " text to make text files"
39+
@echo " man to make manual pages"
40+
@echo " texinfo to make Texinfo files"
41+
@echo " info to make Texinfo files and run them through makeinfo"
42+
@echo " gettext to make PO message catalogs"
43+
@echo " changes to make an overview of all changed/added/deprecated items"
44+
@echo " xml to make Docutils-native XML files"
45+
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
46+
@echo " linkcheck to check all external links for integrity"
47+
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
48+
@echo " coverage to run coverage check of the documentation (if enabled)"
49+
50+
clean:
51+
rm -rf $(BUILDDIR)/*
52+
53+
html:
54+
doxygen
55+
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
56+
@echo
57+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
58+
59+
dirhtml:
60+
doxygen
61+
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
62+
@echo
63+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
64+
65+
singlehtml:
66+
doxygen
67+
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
68+
@echo
69+
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
70+
71+
pickle:
72+
doxygen
73+
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
74+
@echo
75+
@echo "Build finished; now you can process the pickle files."
76+
77+
json:
78+
doxygen
79+
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
80+
@echo
81+
@echo "Build finished; now you can process the JSON files."
82+
83+
htmlhelp:
84+
doxygen
85+
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
86+
@echo
87+
@echo "Build finished; now you can run HTML Help Workshop with the" \
88+
".hhp project file in $(BUILDDIR)/htmlhelp."
89+
90+
epub:
91+
doxygen
92+
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
93+
@echo
94+
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
95+
96+
latex:
97+
doxygen
98+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
99+
@echo
100+
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
101+
@echo "Run \`make' in that directory to run these through (pdf)latex" \
102+
"(use \`make latexpdf' here to do that automatically)."
103+
104+
latexpdf:
105+
doxygen
106+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
107+
@echo "Running LaTeX files through pdflatex..."
108+
$(MAKE) -C $(BUILDDIR)/latex all-pdf
109+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
110+
111+
latexpdfja:
112+
doxygen
113+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
114+
@echo "Running LaTeX files through platex and dvipdfmx..."
115+
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
116+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
117+
118+
text:
119+
doxygen
120+
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
121+
@echo
122+
@echo "Build finished. The text files are in $(BUILDDIR)/text."
123+
124+
man:
125+
doxygen
126+
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
127+
@echo
128+
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
129+
130+
texinfo:
131+
doxygen
132+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
133+
@echo
134+
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
135+
@echo "Run \`make' in that directory to run these through makeinfo" \
136+
"(use \`make info' here to do that automatically)."
137+
138+
info:
139+
doxygen
140+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
141+
@echo "Running Texinfo files through makeinfo..."
142+
make -C $(BUILDDIR)/texinfo info
143+
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
144+
145+
gettext:
146+
doxygen
147+
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
148+
@echo
149+
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
150+
151+
changes:
152+
doxygen
153+
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
154+
@echo
155+
@echo "The overview file is in $(BUILDDIR)/changes."
156+
157+
linkcheck:
158+
doxygen
159+
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
160+
@echo
161+
@echo "Link check complete; look for any errors in the above output " \
162+
"or in $(BUILDDIR)/linkcheck/output.txt."
163+
164+
doctest:
165+
doxygen
166+
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
167+
@echo "Testing of doctests in the sources finished, look at the " \
168+
"results in $(BUILDDIR)/doctest/output.txt."
169+
170+
coverage:
171+
doxygen
172+
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
173+
@echo "Testing of coverage in the sources finished, look at the " \
174+
"results in $(BUILDDIR)/coverage/python.txt."
175+
176+
xml:
177+
doxygen
178+
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
179+
@echo
180+
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
181+
182+
pseudoxml:
183+
doxygen
184+
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
185+
@echo
186+
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

‎docs/environment.yml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
name: xtensor-python-docs
2+
3+
channels:
4+
- conda-forge
5+
6+
dependencies:
7+
- breathe

0 commit comments

Comments
 (0)