Skip to content

Commit 07df46f

Browse files
jbvimortjbvimort
committed
DOC: Creation of a sphinx documentation
1 parent 2c56118 commit 07df46f

File tree

8 files changed

+379
-0
lines changed

8 files changed

+379
-0
lines changed

‎doc/Automated_wheels_building_with_scripts.rst‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
======================================
2+
Automated wheels building with scripts
3+
======================================
4+
5+
Steps required to build wheels on Linux, MacOSX and Windows have been automated. The following sections outline how to use the associated scripts.
6+
7+
Linux
8+
-----
9+
10+
On any linux distribution with docker and bash installed, running the script dockcross-manylinux-build-wheels.sh will create 64-bit wheels for both python 2.x and python 3.x in the dist directory.
11+
12+
For example::
13+
14+
$ git clone https://github.com/InsightSoftwareConsortium/ITKPythonPackage.git
15+
[...]
16+
17+
$ ./scripts/dockcross-manylinux-build-wheels.sh
18+
[...]
19+
20+
$ ls -1 dist/
21+
itk-4.11.0.dev20170218-cp27-cp27m-manylinux1_x86_64.whl
22+
itk-4.11.0.dev20170218-cp27-cp27mu-manylinux1_x86_64.whl
23+
itk-4.11.0.dev20170218-cp34-cp34m-manylinux1_x86_64.whl
24+
itk-4.11.0.dev20170218-cp35-cp35m-manylinux1_x86_64.whl
25+
itk-4.11.0.dev20170218-cp36-cp36m-manylinux1_x86_64.whl
26+
27+
MacOSX
28+
------
29+
30+
First install the Python.org MacOSX Python's. This step requires sudo::
31+
32+
./scripts/macpython-install-python.sh
33+
34+
35+
Then, build the wheels::
36+
37+
$ ./scripts/macpython-build-wheels.sh
38+
[...]
39+
40+
$ ls -1 dist/
41+
itk-4.11.0.dev20170213-cp27-cp27m-macosx_10_6_x86_64.whl
42+
itk-4.11.0.dev20170213-cp34-cp34m-macosx_10_6_x86_64.whl
43+
itk-4.11.0.dev20170213-cp35-cp35m-macosx_10_6_x86_64.whl
44+
itk-4.11.0.dev20170213-cp36-cp36m-macosx_10_6_x86_64.whl
45+
46+
Windows
47+
-------
48+
49+
First, install Microsoft Visual C++ Compiler for Python 2.7, Visual Studio 2015, Git, and CMake, which should be added to the system PATH environmental variable.
50+
51+
Open a PowerShell terminal as Administrator, and install Python::
52+
53+
PS C:\> Set-ExecutionPolicy Unrestricted
54+
PS C:\> iex ((new-object net.webclient).DownloadString('https://raw.githubusercontent.com/scikit-build/scikit-ci-addons/master/windows/install-python.ps1'))
55+
56+
In a PowerShell prompt::
57+
58+
PS C:\Windows> cd C:\
59+
PS C:\> git clone https://github.com/InsightSoftwareConsortium/ITKPythonPackage.git IPP
60+
PS C:\> cd IPP
61+
PS C:\IPP> .\scripts\windows-build-wheels.ps1
62+
[...]
63+
64+
PS C:\IPP> ls dist
65+
Directory: C:\IPP\dist
66+
67+
68+
Mode LastWriteTime Length Name
69+
---- ------------- ------ ----
70+
-a---- 4/9/2017 5:21 PM 59435508 itk-4.11.0.dev20170407-cp27-cp27m-win_amd64.whl
71+
-a---- 4/9/2017 11:14 PM 63274441 itk-4.11.0.dev20170407-cp35-cp35m-win_amd64.whl
72+
-a---- 4/10/2017 2:08 AM 63257220 itk-4.11.0.dev20170407-cp36-cp36m-win_amd64.whl
73+
74+
We need to work in a short directory to avoid path length limitations on Windows, so the repository is cloned into C:\IPP. Also, it is very important to disable antivirus checking on the C:\IPP directory. Otherwise, the build system conflicts with the antivirus when many files are created and deleted quickly, which can result in Access Denied errors. Windows 10 ships with an antivirus application, Windows Defender, that is enabled by default.
75+
76+
sdist
77+
-----
78+
79+
To create source distributions, sdist's, that will be used by pip to compile a wheel for installation if a binary wheel is not available for the current Python version or platform::
80+
81+
$ python setup.py sdist --formats=gztar,zip
82+
[...]
83+
84+
$ ls -1 dist/
85+
itk-4.11.0.dev20170216.tar.gz
86+
itk-4.11.0.dev20170216.zip

‎doc/Detailed_build_instructions.rst‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
===========================
2+
Detailed build instructions
3+
===========================
4+
5+
Building ITK Python wheels
6+
--------------------------
7+
8+
Build the ITK Python wheel with the following command::
9+
10+
mkvirtualenv build-itk
11+
pip install -r requirements-dev.txt
12+
python setup.py bdist_wheel
13+
14+
Efficiently building wheels for different version of python
15+
-----------------------------------------------------------
16+
17+
If on a given platform you would like to build wheels for different version of python, you can download and build the ITK components independent from python first and reuse them when building each wheel.
18+
19+
Here are the steps:
20+
21+
- Build ITKPythonPackage with ITKPythonPackage_BUILD_PYTHON set to OFF
22+
23+
- Build "flavor" of package using::
24+
25+
python setup.py bdist_wheel -- \
26+
-DITK_SOURCE_DIR:PATH=/path/to/ITKPythonPackage-core-build/ITK-source

‎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.
5+
SPHINXOPTS =
6+
SPHINXBUILD = python -msphinx
7+
SPHINXPROJ = ITKPythonPackage
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/Miscellaneous.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
=============
2+
Miscellaneous
3+
=============
4+
5+
Written by Jean-Christophe Fillion-Robin and Matt McCormick from Kitware Inc.
6+
7+
It is covered by the Apache License, Version 2.0:
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
For more information about ITK, visit http://itk.org

‎doc/Prerequisites.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
=============
2+
Prerequisites
3+
=============
4+
5+
Building wheels requires:
6+
7+
- CMake
8+
- Git
9+
- C++ Compiler - Platform specific requirements are summarized in scikit-build documentation.
10+
- Python

‎doc/conf.py‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# ITKPythonPackage documentation build configuration file, created by
4+
# sphinx-quickstart on Mon May 29 15:53:20 2017.
5+
#
6+
# This file is execfile()d with the current directory set to its
7+
# containing dir.
8+
#
9+
# Note that not all possible configuration values are present in this
10+
# autogenerated file.
11+
#
12+
# All configuration values have a default; values that are commented out
13+
# serve to show the default.
14+
15+
# If extensions (or modules to document with autodoc) are in another directory,
16+
# add these directories to sys.path here. If the directory is relative to the
17+
# documentation root, use os.path.abspath to make it absolute, like shown here.
18+
#
19+
# import os
20+
# import sys
21+
# sys.path.insert(0, os.path.abspath('.'))
22+
23+
24+
# -- General configuration ------------------------------------------------
25+
26+
# If your documentation needs a minimal Sphinx version, state it here.
27+
#
28+
# needs_sphinx = '1.0'
29+
30+
# Add any Sphinx extension module names here, as strings. They can be
31+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
32+
# ones.
33+
extensions = []
34+
35+
# Add any paths that contain templates here, relative to this directory.
36+
templates_path = ['_templates']
37+
38+
# The suffix(es) of source filenames.
39+
# You can specify multiple suffix as a list of string:
40+
#
41+
# source_suffix = ['.rst', '.md']
42+
source_suffix = '.rst'
43+
44+
# The master toctree document.
45+
master_doc = 'index'
46+
47+
# General information about the project.
48+
project = u'ITKPythonPackage'
49+
copyright = u'2017, Jean-Christophe Fillion-Robin and Matt McCormick'
50+
author = u'Jean-Christophe Fillion-Robin and Matt McCormick'
51+
52+
# The version info for the project you're documenting, acts as replacement for
53+
# |version| and |release|, also used in various other places throughout the
54+
# built documents.
55+
#
56+
# The short X.Y version.
57+
version = u''
58+
# The full version, including alpha/beta/rc tags.
59+
release = u''
60+
61+
# The language for content autogenerated by Sphinx. Refer to documentation
62+
# for a list of supported languages.
63+
#
64+
# This is also used if you do content translation via gettext catalogs.
65+
# Usually you set "language" from the command line for these cases.
66+
language = None
67+
68+
# List of patterns, relative to source directory, that match files and
69+
# directories to ignore when looking for source files.
70+
# This patterns also effect to html_static_path and html_extra_path
71+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
72+
73+
# The name of the Pygments (syntax highlighting) style to use.
74+
pygments_style = 'sphinx'
75+
76+
# If true, `todo` and `todoList` produce output, else they produce nothing.
77+
todo_include_todos = False
78+
79+
80+
# -- Options for HTML output ----------------------------------------------
81+
82+
# The theme to use for HTML and HTML Help pages. See the documentation for
83+
# a list of builtin themes.
84+
#
85+
html_theme = 'alabaster'
86+
87+
# Theme options are theme-specific and customize the look and feel of a theme
88+
# further. For a list of options available for each theme, see the
89+
# documentation.
90+
#
91+
# html_theme_options = {}
92+
93+
# Add any paths that contain custom static files (such as style sheets) here,
94+
# relative to this directory. They are copied after the builtin static files,
95+
# so a file named "default.css" will overwrite the builtin "default.css".
96+
html_static_path = ['_static']
97+
98+
99+
# -- Options for HTMLHelp output ------------------------------------------
100+
101+
# Output file base name for HTML help builder.
102+
htmlhelp_basename = 'ITKPythonPackagedoc'
103+
104+
105+
# -- Options for LaTeX output ---------------------------------------------
106+
107+
latex_elements = {
108+
# The paper size ('letterpaper' or 'a4paper').
109+
#
110+
# 'papersize': 'letterpaper',
111+
112+
# The font size ('10pt', '11pt' or '12pt').
113+
#
114+
# 'pointsize': '10pt',
115+
116+
# Additional stuff for the LaTeX preamble.
117+
#
118+
# 'preamble': '',
119+
120+
# Latex figure (float) alignment
121+
#
122+
# 'figure_align': 'htbp',
123+
}
124+
125+
# Grouping the document tree into LaTeX files. List of tuples
126+
# (source start file, target name, title,
127+
# author, documentclass [howto, manual, or own class]).
128+
latex_documents = [
129+
(master_doc, 'ITKPythonPackage.tex', u'ITKPythonPackage Documentation',
130+
u'Jean-Christophe Fillion-Robin and Matt McCormick', 'manual'),
131+
]
132+
133+
134+
# -- Options for manual page output ---------------------------------------
135+
136+
# One entry per manual page. List of tuples
137+
# (source start file, name, description, authors, manual section).
138+
man_pages = [
139+
(master_doc, 'itkpythonpackage', u'ITKPythonPackage Documentation',
140+
[author], 1)
141+
]
142+
143+
144+
# -- Options for Texinfo output -------------------------------------------
145+
146+
# Grouping the document tree into Texinfo files. List of tuples
147+
# (source start file, target name, title, author,
148+
# dir menu entry, description, category)
149+
texinfo_documents = [
150+
(master_doc, 'ITKPythonPackage', u'ITKPythonPackage Documentation',
151+
author, 'ITKPythonPackage', 'One line description of project.',
152+
'Miscellaneous'),
153+
]
154+
155+
156+

‎doc/index.rst‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
.. ITKPythonPackage documentation master file, created by
2+
sphinx-quickstart on Mon May 29 14:09:52 2017.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Welcome to ITKPythonPackage's documentation!
7+
============================================
8+
9+
This project provides a ``setup.py`` script that build ITK Python wheels.
10+
11+
ITK is an open-source, cross-platform system that provides developers with an extensive suite of software tools for image analysis.
12+
13+
The Python packages are built daily. To install the ITK Python package::
14+
15+
$ python -m pip install --upgrade pip
16+
$ python -m pip install itk -f https://github.com/InsightSoftwareConsortium/ITKPythonPackage/releases/tag/latest
17+
18+
For more information on ITK's Python wrapping, see an introduction in the ITK Software Guide. There are also many downloadable examples documented in Sphinx.
19+
20+
.. toctree::
21+
:maxdepth: 2
22+
:caption: Contents
23+
24+
Automated_wheels_building_with_scripts.rst
25+
Prerequisites.rst
26+
Detailed_build_instructions.rst
27+
Miscellaneous.rst
28+
29+
Indices and tables
30+
==================
31+
32+
* :ref:`genindex`
33+
* :ref:`modindex`
34+
* :ref:`search`

‎doc/make.bat‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=python -msphinx
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
set SPHINXPROJ=ITKPythonPackage
13+
14+
if "%1" == "" goto help
15+
16+
%SPHINXBUILD% >NUL 2>NUL
17+
if errorlevel 9009 (
18+
echo.
19+
echo.The Sphinx module was not found. Make sure you have Sphinx installed,
20+
echo.then set the SPHINXBUILD environment variable to point to the full
21+
echo.path of the 'sphinx-build' executable. Alternatively you may add the
22+
echo.Sphinx directory to PATH.
23+
echo.
24+
echo.If you don't have Sphinx installed, grab it from
25+
echo.http://sphinx-doc.org/
26+
exit /b 1
27+
)
28+
29+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
30+
goto end
31+
32+
:help
33+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
34+
35+
:end
36+
popd

0 commit comments

Comments
 (0)