Skip to content

Commit 3757d95

Browse files
scoopxyzscoopxyz
authored
initial v2 doc restructure (#1075)
* initial doc restructure Signed-off-by: Sean Cooper <[email protected]> * rename file to avoid conflict Signed-off-by: Sean Cooper <[email protected]> * rename directory to avoid conflict` Signed-off-by: Sean Cooper <[email protected]> * fix readme Signed-off-by: Sean Cooper <[email protected]> * add images back Signed-off-by: Sean Cooper <[email protected]> * add python dependencies Signed-off-by: Sean Cooper <[email protected]> * remove min version Signed-off-by: Sean Cooper <[email protected]> * add find_python_package Signed-off-by: Sean Cooper <[email protected]> * update dependencies Signed-off-by: Sean Cooper <[email protected]> * add python2 blocking to doc generation Signed-off-by: Sean Cooper <[email protected]> * add local pip install pythonpath Signed-off-by: Sean Cooper <[email protected]> * remove recommonmark Signed-off-by: Sean Cooper <[email protected]> * add min version Signed-off-by: Sean Cooper <[email protected]> * reduce python dependencies modify python macro to support dependencies Signed-off-by: Sean Cooper <[email protected]> * update dependencies Signed-off-by: Sean Cooper <[email protected]> * update python pip prefix Signed-off-by: Sean Cooper <[email protected]> * swap to original sphinx-press-theme Signed-off-by: Sean Cooper <[email protected]> * reconfigure docs target dependencies Signed-off-by: Sean Cooper <[email protected]> * temporarily disable windows docs builds Signed-off-by: Sean Cooper <[email protected]>
1 parent d431b29 commit 3757d95

File tree

144 files changed

+523
-955
lines changed

Some content is hidden

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

144 files changed

+523
-955
lines changed

‎docs/.nojekyll renamed to ‎.nojekyll

File renamed without changes.

‎docs/CMakeLists.txt

Lines changed: 152 additions & 136 deletions
Original file line numberDiff line numberDiff line change
@@ -4,172 +4,188 @@
44
###############################################################################
55
### Python ###
66
find_package(Python REQUIRED COMPONENTS Interpreter)
7-
if(NOT OCIO_BUILD_PYTHON)
8-
message(FATAL_ERROR "Doc generation requires that the python bindings be built")
9-
endif()
7+
if((${Python_VERSION_MAJOR} GREATER_EQUAL 3) AND (NOT WIN32))
8+
if(NOT OCIO_BUILD_PYTHON)
9+
message(FATAL_ERROR "Doc generation requires that the python bindings be built")
10+
endif()
1011

11-
###############################################################################
12-
### Setup PYTHONPATH ###
13-
14-
# Override PYTHONPATH prior to running Sphinx. This makes the PyOpenColorIO
15-
# build available, prioritizes ext/ installed Python dependencies, and
16-
# propagates the system PYTHONPATH.
17-
if(WIN32)
18-
# Use Windows path separators since this is being passed through to cmd
19-
file(TO_NATIVE_PATH ${CMAKE_BINARY_DIR} WIN_BINARY_DIR)
20-
21-
set(DLL_PATH "${WIN_BINARY_DIR}\\src\\OpenColorIO")
22-
if(MSVC_IDE)
23-
set(DLL_PATH "${DLL_PATH}\\${CMAKE_BUILD_TYPE}")
12+
###############################################################################
13+
### Setup PYTHONPATH ###
14+
15+
# Override PYTHONPATH prior to running Sphinx. This makes the PyOpenColorIO
16+
# build available, prioritizes ext/ installed Python dependencies, and
17+
# propagates the system PYTHONPATH.
18+
if(WIN32)
19+
# Use Windows path separators since this is being passed through to cmd
20+
file(TO_NATIVE_PATH ${CMAKE_BINARY_DIR} WIN_BINARY_DIR)
21+
22+
set(DLL_PATH "${WIN_BINARY_DIR}\\src\\OpenColorIO")
23+
if(MSVC_IDE)
24+
set(DLL_PATH "${DLL_PATH}\\${CMAKE_BUILD_TYPE}")
25+
endif()
26+
27+
string(CONCAT PATH_SET
28+
"PATH="
29+
"${DLL_PATH}"
30+
"\\\\;"
31+
"%PATH%"
32+
)
33+
34+
set(PYD_PATH "${WIN_BINARY_DIR}\\src\\bindings\\python")
35+
if(MSVC_IDE)
36+
set(PYD_PATH "${PYD_PATH}\\${CMAKE_BUILD_TYPE}")
37+
endif()
38+
39+
string(CONCAT PYTHONPATH_SET
40+
"PYTHONPATH="
41+
"${PYD_PATH}"
42+
"\\\\;"
43+
"${WIN_BINARY_DIR}\\ext\\dist\\lib${LIB_SUFFIX}\\site-packages"
44+
"\\\\;"
45+
"%PYTHONPATH%"
46+
)
47+
# Mimic *nix:
48+
# '> PYTHONPATH=XXX CMD'
49+
# on Windows with:
50+
# '> set PYTHONPATH=XXX \n call CMD'
51+
# '\n' is here because '\\&' does not work.
52+
set(PYT_PRE_CMD set ${PATH_SET} "\n" set ${PYTHONPATH_SET} "\n" call)
53+
54+
else()
55+
set(_Python_VARIANT "${Python_VERSION_MAJOR}.${Python_VERSION_MINOR}")
56+
string(CONCAT PYT_PRE_CMD
57+
"PYTHONPATH="
58+
"${CMAKE_BINARY_DIR}/src/bindings/python"
59+
":"
60+
"${CMAKE_BINARY_DIR}/ext/dist/lib${LIB_SUFFIX}/python${_Python_VARIANT}/site-packages"
61+
":"
62+
"$ENV{PYTHONPATH}"
63+
)
2464
endif()
2565

26-
string(CONCAT PATH_SET
27-
"PATH="
28-
"${DLL_PATH}"
29-
"\\\\;"
30-
"%PATH%"
31-
)
66+
###############################################################################
67+
### Copy templates to build area ###
3268

33-
set(PYD_PATH "${WIN_BINARY_DIR}\\src\\bindings\\python")
34-
if(MSVC_IDE)
35-
set(PYD_PATH "${PYD_PATH}\\${CMAKE_BUILD_TYPE}")
69+
file(GLOB_RECURSE DOC_SOURCES "${CMAKE_SOURCE_DIR}/docs/*")
70+
list(APPEND DOC_SOURCES
71+
${CMAKE_SOURCE_DIR}/README.md
72+
${CMAKE_SOURCE_DIR}/INSTALL.md
73+
${CMAKE_SOURCE_DIR}/CHANGELOG.md
74+
${CMAKE_SOURCE_DIR}/LICENSE
75+
)
76+
if(OCIO_BUILD_NUKE)
77+
list(APPEND DOC_SOURCES ${CMAKE_SOURCE_DIR}/share/nuke/ocionuke/viewer.py)
3678
endif()
3779

38-
string(CONCAT PYTHONPATH_SET
39-
"PYTHONPATH="
40-
"${PYD_PATH}"
41-
"\\\\;"
42-
"${WIN_BINARY_DIR}\\ext\\dist\\lib\\site-packages"
43-
"\\\\;"
44-
"%PYTHONPATH%"
80+
add_custom_target(doc_copy
81+
COMMENT "Copying doc files to staging area"
4582
)
46-
# Mimic *nix:
47-
# '> PYTHONPATH=XXX CMD'
48-
# on Windows with:
49-
# '> set PYTHONPATH=XXX \n call CMD'
50-
# '\n' is here because '\\&' does not work.
51-
set(PYT_PRE_CMD set ${PATH_SET} "\n" set ${PYTHONPATH_SET} "\n" call)
5283

53-
else()
54-
set(_Python_VARIANT "${Python_VERSION_MAJOR}.${Python_VERSION_MINOR}")
55-
string(CONCAT PYT_PRE_CMD
56-
"PYTHONPATH="
57-
"${CMAKE_BINARY_DIR}/src/bindings/python"
58-
":"
59-
"${CMAKE_BINARY_DIR}/ext/dist/lib${LIB_SUFFIX}/python${_Python_VARIANT}/site-packages"
60-
":"
61-
"$ENV{PYTHONPATH}"
84+
foreach(f ${DOC_SOURCES})
85+
string(REGEX REPLACE "^${CMAKE_SOURCE_DIR}/" "" relpath ${f})
86+
string(REGEX REPLACE "[/. ]" "_" tgtname ${relpath})
87+
string(REGEX MATCH "^docs" IN_DOCS ${relpath})
88+
89+
set(SRC_PATH ${CMAKE_SOURCE_DIR}/${relpath})
90+
set(DST_PATH ${CMAKE_BINARY_DIR}/${relpath})
91+
if(NOT IN_DOCS)
92+
get_filename_component(F_NAME ${relpath} NAME)
93+
set(DST_PATH "${CMAKE_BINARY_DIR}/docs/${F_NAME}")
94+
endif()
95+
96+
add_custom_command(OUTPUT ${DST_PATH}
97+
COMMAND ${CMAKE_COMMAND} -E copy ${SRC_PATH} ${DST_PATH}
98+
DEPENDS ${SRC_PATH}
99+
)
100+
add_custom_target("copy_${tgtname}" DEPENDS ${DST_PATH})
101+
add_dependencies(doc_copy "copy_${tgtname}")
102+
endforeach()
103+
104+
###############################################################################
105+
### Extract rst from c++ headers ###
106+
107+
set(EXTRACT_COMMAND "${CMAKE_SOURCE_DIR}/share/sphinx/ExtractRstFromSourceCPP.py")
108+
set(OCIO_HEADER_DIR "${CMAKE_SOURCE_DIR}/include/OpenColorIO")
109+
set(RST_DESTINATION "${CMAKE_BINARY_DIR}/docs/developers/api/")
110+
add_custom_target(rst_extraction
111+
COMMAND ${CMAKE_COMMAND} -E make_directory ${RST_DESTINATION}
112+
COMMAND ${Python_EXECUTABLE} ${EXTRACT_COMMAND} ${OCIO_HEADER_DIR}/OpenColorIO.h ${RST_DESTINATION}/OpenColorIO.rst
113+
COMMAND ${Python_EXECUTABLE} ${EXTRACT_COMMAND} ${OCIO_HEADER_DIR}/OpenColorTransforms.h ${RST_DESTINATION}/OpenColorTransforms.rst
114+
COMMAND ${Python_EXECUTABLE} ${EXTRACT_COMMAND} ${OCIO_HEADER_DIR}/OpenColorTypes.h ${RST_DESTINATION}/OpenColorTypes.rst
115+
COMMENT "Extracting .rst files from C++ headers"
62116
)
63-
endif()
64-
65-
###############################################################################
66-
### Copy templates to build area ###
67-
68-
message(STATUS "Create sphinx conf.py from conf.py.in")
69-
configure_file(conf.py.in ${CMAKE_BINARY_DIR}/docs/conf.py @ONLY)
70-
71-
file(GLOB_RECURSE DOC_SOURCES "${CMAKE_SOURCE_DIR}/docs/*")
72-
list(APPEND DOC_SOURCES
73-
${CMAKE_SOURCE_DIR}/README.md
74-
${CMAKE_SOURCE_DIR}/INSTALL.md
75-
${CMAKE_SOURCE_DIR}/CHANGELOG.md
76-
${CMAKE_SOURCE_DIR}/LICENSE
77-
)
78-
if(OCIO_BUILD_NUKE)
79-
list(APPEND DOC_SOURCES ${CMAKE_SOURCE_DIR}/share/nuke/ocionuke/viewer.py)
80-
endif()
81-
82-
add_custom_target(doc_copy
83-
COMMENT "Copying doc files to staging area"
84-
)
85117

86-
foreach(f ${DOC_SOURCES})
87-
string(REGEX REPLACE "^${CMAKE_SOURCE_DIR}/" "" relpath ${f})
88-
string(REGEX REPLACE "[/. ]" "_" tgtname ${relpath})
89-
string(REGEX MATCH "^docs" IN_DOCS ${relpath})
118+
###############################################################################
119+
### HTML doc target ###
90120

91-
set(SRC_PATH ${CMAKE_SOURCE_DIR}/${relpath})
92-
set(DST_PATH ${CMAKE_BINARY_DIR}/${relpath})
93-
if(NOT IN_DOCS)
94-
get_filename_component(F_NAME ${relpath} NAME)
95-
set(DST_PATH "${CMAKE_BINARY_DIR}/docs/${F_NAME}")
96-
endif()
97-
98-
add_custom_command(OUTPUT ${DST_PATH}
99-
COMMAND ${CMAKE_COMMAND} -E copy ${SRC_PATH} ${DST_PATH}
100-
DEPENDS ${SRC_PATH}
121+
add_custom_target(docs ALL
122+
COMMAND
123+
${PYT_PRE_CMD} "${Sphinx_EXECUTABLE}" -b html . "${CMAKE_CURRENT_BINARY_DIR}/build-html"
124+
DEPENDS
125+
${CMAKE_BINARY_DIR}/docs/conf.py
126+
COMMENT "Building html docs"
101127
)
102-
add_custom_target("copy_${tgtname}" DEPENDS ${DST_PATH})
103-
add_dependencies(doc_copy "copy_${tgtname}")
104-
endforeach()
105-
106-
###############################################################################
107-
### Extract rst from c++ headers ###
108-
109-
set(EXTRACT_COMMAND "${CMAKE_SOURCE_DIR}/share/sphinx/ExtractRstFromSourceCPP.py")
110-
set(OCIO_HEADER_DIR "${CMAKE_SOURCE_DIR}/include/OpenColorIO")
111-
set(RST_DESTINATION "${CMAKE_BINARY_DIR}/docs/developers/api/")
112-
add_custom_target(rst_extraction
113-
COMMAND ${CMAKE_COMMAND} -E make_directory ${RST_DESTINATION}
114-
COMMAND ${Python_EXECUTABLE} ${EXTRACT_COMMAND} ${OCIO_HEADER_DIR}/OpenColorIO.h ${RST_DESTINATION}/OpenColorIO.rst
115-
COMMAND ${Python_EXECUTABLE} ${EXTRACT_COMMAND} ${OCIO_HEADER_DIR}/OpenColorTransforms.h ${RST_DESTINATION}/OpenColorTransforms.rst
116-
COMMAND ${Python_EXECUTABLE} ${EXTRACT_COMMAND} ${OCIO_HEADER_DIR}/OpenColorTypes.h ${RST_DESTINATION}/OpenColorTypes.rst
117-
COMMENT "Extracting .rst files from C++ headers"
118-
)
119128

120-
###############################################################################
121-
### HTML doc target ###
122-
123-
add_custom_target(docs ALL
124-
COMMAND
125-
${PYT_PRE_CMD} "${Sphinx_EXECUTABLE}" -b html . "${CMAKE_CURRENT_BINARY_DIR}/build-html"
126-
DEPENDS
129+
add_dependencies(docs
127130
OpenColorIO
128131
PyOpenColorIO
129-
${CMAKE_BINARY_DIR}/docs/conf.py
130132
rst_extraction
131133
doc_copy
132134
Sphinx
133-
COMMENT "Building html docs"
134-
)
135+
sphinx-press-theme
136+
recommonmark
137+
)
135138

136-
###############################################################################
137-
### Installation ###
139+
###############################################################################
140+
### Installation ###
138141

139-
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/build-html/
140-
DESTINATION ${CMAKE_INSTALL_PREFIX}/share/doc/OpenColorIO/html
141-
PATTERN .* EXCLUDE
142-
)
142+
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/build-html/
143+
DESTINATION ${CMAKE_INSTALL_PREFIX}/share/doc/OpenColorIO/html
144+
PATTERN .* EXCLUDE
145+
)
143146

144-
###############################################################################
145-
### PDF target ###
147+
###############################################################################
148+
### PDF target ###
146149

147-
find_package(LATEX)
148-
package_root_message(LATEX)
150+
find_package(LATEX)
151+
package_root_message(LATEX)
149152

150-
if(PDFLATEX_COMPILER)
153+
if(PDFLATEX_COMPILER)
151154

152-
add_custom_target(latex
153-
COMMAND
154-
${PYT_PRE_CMD} "${Sphinx_EXECUTABLE}" -b latex . "${CMAKE_CURRENT_BINARY_DIR}/build-latex"
155-
DEPENDS
155+
add_custom_target(latex
156+
COMMAND
157+
${PYT_PRE_CMD} "${Sphinx_EXECUTABLE}" -b latex . "${CMAKE_CURRENT_BINARY_DIR}/build-latex"
158+
DEPENDS
159+
${CMAKE_BINARY_DIR}/docs/conf.py
160+
COMMENT "Building latex doc"
161+
)
162+
163+
add_dependencies(latex
156164
OpenColorIO
157165
PyOpenColorIO
158-
${CMAKE_BINARY_DIR}/docs/conf.py
159166
rst_extraction
160167
doc_copy
161168
Sphinx
162-
COMMENT "Building latex doc"
163-
)
169+
sphinx-press-theme
170+
recommonmark
171+
)
164172

165-
add_custom_target(pdf ALL
166-
DEPENDS latex
167-
COMMAND ${PDFLATEX_COMPILER} OpenColorIO.tex
168-
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/build-latex
169-
COMMENT "Building pdf doc"
170-
)
171173

172-
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/build-latex/OpenColorIO.pdf
173-
DESTINATION ${CMAKE_INSTALL_PREFIX}/share/doc/OpenColorIO/)
174+
add_custom_target(pdf ALL
175+
COMMAND ${PDFLATEX_COMPILER} OpenColorIO.tex
176+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/build-latex
177+
COMMENT "Building pdf doc"
178+
)
179+
180+
add_dependencies(pdf
181+
latex
182+
)
174183

184+
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/build-latex/OpenColorIO.pdf
185+
DESTINATION ${CMAKE_INSTALL_PREFIX}/share/doc/OpenColorIO/)
186+
187+
endif()
188+
189+
else()
190+
message(Warning "Skipping local documentation generation, requires Python >= 3.x")
175191
endif()

‎docs/V2_DOC_README.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# OCIO v2 Documentation Effort
2+
3+
Since the API autodoc effort is happening simultaneously it will be easier for
4+
a lot of contributors to do a light-weight build of the Sphinx docs, which
5+
doesn't require building OCIO in its entirety.
6+
7+
## How to Build RST-Only Docs
8+
9+
In addition to the general OCIO v2 dependencies (Python and Sphinx), install the
10+
Python packages listed in the `docs/requirements.txt` file.
11+
12+
```
13+
pip install -r docs/requirements.txt
14+
```
15+
16+
Build the sphinx docs locally...
17+
18+
```
19+
cd docs
20+
mkdir _build
21+
sphinx-build -b html . _build
22+
firefox _build/index.html
23+
```
24+
25+
26+
## Quirks
27+
28+
The vuepress theme that we've migrated to has some quirks to its design. For
29+
example it only allows two nested table of contents (TOC). So things have to be
30+
organized in a slightly different way than other sphinx projects.
31+
32+
The root-level `toc_redirect.rst` points to where to find the different section
33+
TOCs. The name and contents of each sections TOC is defined in that
34+
sub-directory's `_index.rst` file.
35+
36+
In this TOC the `:caption:` directive determines what the name of the section
37+
will be in the side-bar, and in the header of the website. The *H1* header
38+
determines the name of the page in the right/left arrows navigation bar. In a
39+
lot of cases this ends up doubling up the name on the page, but this seems
40+
unavoidable at the present time. If additional explanatory text is put in the
41+
`_index.rst` files then it shouldn't be as problematic.
42+
43+
The site will show all *H1* headers in the side panel by default, these then
44+
expand when selected to show all *H2* headers.
45+
46+
Due to the limited TOC and side-bar depth, we shouldn't be afraid of looong
47+
pages with many *H2* headings to break down the page into logical quadrants.

0 commit comments

Comments
 (0)