Commit 1ed8190c authored by Markus Mirz's avatar Markus Mirz
Browse files

restructure sphinx doxygen docs

parent 64991760
variables:
RSYNC_OPTS: --recursive --ignore-missing-args --chown ${DEPLOY_USER}:${DEPLOY_USER}
DOCKER_TAG: ${CI_COMMIT_REF_NAME}
DOCKER_TAG_DEV: ${CI_COMMIT_REF_NAME}
DOCKER_IMAGE: rwthacs/dpsim
DOCKER_IMAGE_DEV: rwthacs/dpsim-dev
......@@ -22,14 +21,14 @@ docker:
script:
- docker build
--file Packaging/Docker/Dockerfile.dev
--tag ${DOCKER_IMAGE_DEV}:${DOCKER_TAG_DEV}
--tag ${DOCKER_IMAGE_DEV}:${DOCKER_TAG}
--tag ${DOCKER_IMAGE_DEV}:latest .
# build dedicated jupyter image in the future
- docker build
--file Packaging/Docker/Dockerfile.jupyter
--build-arg DOCKER_IMAGE=${DOCKER_IMAGE_DEV}
--build-arg DOCKER_TAG=${DOCKER_TAG_DEV}
--tag ${DOCKER_IMAGE_DEV}-jupyter:${DOCKER_TAG_DEV}
--build-arg DOCKER_TAG=${DOCKER_TAG}
--tag ${DOCKER_IMAGE_DEV}-jupyter:${DOCKER_TAG}
--tag ${DOCKER_IMAGE_DEV}-jupyter:latest .
tags:
- shell
......@@ -42,7 +41,7 @@ build:linux:
- cd build
- cmake ..
- make -j 32
image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG_DEV}
image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG}
cache:
paths:
- build
......@@ -102,7 +101,7 @@ build:windows:
# - pytest -v Examples/Python/Circuits
# - pytest -v Examples/Python/RealTime
# #- pytest -v Examples/Python/Shmem
# image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG_DEV}
# image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG}
# dependencies:
# - build:linux
# tags:
......@@ -113,7 +112,7 @@ generate:docs:
script:
- make -j$(nproc) -C build docs
- make -j$(nproc) -C build docs_cxx
image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG_DEV}
image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG}
dependencies:
- build:linux
artifacts:
......@@ -131,7 +130,7 @@ generate:packages:
- tags
tags:
- docker
image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG_DEV}
image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG}
dependencies:
- build:linux
artifacts:
......@@ -163,7 +162,7 @@ test:jupyter:
PYTHONPATH: "build/Source/Python:Source/Python"
script:
- pytest -v Examples/Notebooks
image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG_DEV}
image: ${DOCKER_IMAGE_DEV}:${DOCKER_TAG}
dependencies:
- build:linux
tags:
......@@ -177,8 +176,8 @@ test:jupyter:
pages:
stage: deploy
script:
- cp -r build/docs/html/. public
- cp -r build/docs/Cxx/html/. public/cxx
- cp -r build/docs/sphinx/html/. public/sphinx
- cp -r build/docs/doxygen/html/. public/doxygen
artifacts:
paths:
- public
......@@ -193,7 +192,7 @@ pages:
deploy:docker:
stage: deploy
script:
- docker push ${DOCKER_IMAGE_DEV}:${DOCKER_TAG_DEV}
- docker push ${DOCKER_IMAGE_DEV}:${DOCKER_TAG}
- docker push ${DOCKER_IMAGE_DEV}:latest
- docker push ${DOCKER_IMAGE}:${DOCKER_TAG}
- docker push ${DOCKER_IMAGE}:latest
......
This directory contains the Python code of the `dpsim` module.
It is merely a wrapper around the native `_dpsim` C++ extension.
\ No newline at end of file
if(WITH_PYTHON)
find_package(Sphinx)
if(SPHINX_EXECUTABLE)
# configured documentation tools and intermediate build results
set(BINARY_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/_build")
# Sphinx cache with pickled ReST documents
set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees")
# HTML output directory
set(SPHINX_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/html")
set(SPHINX_TITLE "${PROJECT_NAME} docs")
configure_file(
"${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in"
"${BINARY_BUILD_DIR}/conf.py"
@ONLY
)
# We add the path of the freshly build dpsim.so module to Python path here
add_custom_target(docs
COMMAND
${CMAKE_COMMAND} -E env PYTHONPATH=$<TARGET_FILE_DIR:dpsim_python>:${CMAKE_CURRENT_SOURCE_DIR}/../Source/Python/:$ENV{PYTHONPATH}
${SPHINX_EXECUTABLE}
-q -b html
-c "${BINARY_BUILD_DIR}"
-d "${SPHINX_CACHE_DIR}"
"${CMAKE_CURRENT_SOURCE_DIR}"
"${SPHINX_HTML_DIR}"
COMMENT "Building HTML documentation with Sphinx"
DEPENDS
dpsim_python
)
endif()
endif()
# add a target to generate API documentation with Doxygen
find_package(Doxygen)
if(DOXYGEN_FOUND)
configure_file(
"${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in"
"${CMAKE_CURRENT_BINARY_DIR}/Doxyfile"
@ONLY
)
# HTML output directory
set(DOXYGEN_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/Cxx")
file(MAKE_DIRECTORY ${DOXYGEN_HTML_DIR})
# Copy figures into Doxygen working directory
add_custom_target(copy_imgs_cxx
COMMAND
${CMAKE_COMMAND} -E make_directory
"${CMAKE_CURRENT_BINARY_DIR}/Cxx/html/images/"
COMMAND
${CMAKE_COMMAND} -E copy
"${CMAKE_CURRENT_SOURCE_DIR}/images/dpsim.png"
"${CMAKE_CURRENT_BINARY_DIR}/Cxx/html/images/"
COMMENT "Copy figures to Doxygen output dir"
)
add_custom_target(docs_cxx
COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMENT "Generating API documentation with Doxygen" VERBATIM
DEPENDS
copy_imgs_cxx
)
endif(DOXYGEN_FOUND)
add_subdirectory(sphinx)
add_subdirectory(doxygen)
\ No newline at end of file
find_package(Doxygen)
if(DOXYGEN_FOUND)
configure_file(
"${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in"
"${CMAKE_CURRENT_BINARY_DIR}/Doxyfile"
@ONLY
)
# HTML output directory
set(DOXYGEN_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/doxygen")
file(MAKE_DIRECTORY ${DOXYGEN_HTML_DIR})
add_custom_target(docs_cxx
COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMENT "Generating API documentation with Doxygen" VERBATIM
)
endif(DOXYGEN_FOUND)
\ No newline at end of file
......@@ -58,7 +58,7 @@ PROJECT_LOGO =
# entered, it will be relative to the location where doxygen was started. If
# left blank the current directory will be used.
OUTPUT_DIRECTORY = @CMAKE_CURRENT_BINARY_DIR@/Cxx/
OUTPUT_DIRECTORY = @CMAKE_CURRENT_BINARY_DIR@/
# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
# directories (in 2 levels) under the output directory of each output format and
......@@ -790,11 +790,11 @@ WARN_LOGFILE =
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
INPUT = @CMAKE_CURRENT_SOURCE_DIR@/../docs/DoxyMain.md \
@CMAKE_CURRENT_SOURCE_DIR@/../Source \
@CMAKE_CURRENT_SOURCE_DIR@/../Include \
@CMAKE_CURRENT_SOURCE_DIR@/../models/Source \
@CMAKE_CURRENT_SOURCE_DIR@/../models/Include
INPUT = @CMAKE_CURRENT_SOURCE_DIR@/DoxyMain.md \
@CMAKE_CURRENT_SOURCE_DIR@/../../Source \
@CMAKE_CURRENT_SOURCE_DIR@/../../Include \
@CMAKE_CURRENT_SOURCE_DIR@/../../models/Source \
@CMAKE_CURRENT_SOURCE_DIR@/../../models/Include
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
......@@ -910,7 +910,7 @@ EXCLUDE_SYMBOLS =
# that contain example code fragments that are included (see the \include
# command).
EXAMPLE_PATH = Examples/Cxx/
EXAMPLE_PATH =
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
......@@ -986,7 +986,7 @@ FILTER_SOURCE_PATTERNS =
# (index.html). This can be useful if you have a project on for instance GitHub
# and want to reuse the introduction page also for the doxygen output.
USE_MDFILE_AS_MAINPAGE = @CMAKE_CURRENT_SOURCE_DIR@/../docs/DoxyMain.md
USE_MDFILE_AS_MAINPAGE = @CMAKE_CURRENT_SOURCE_DIR@/DoxyMain.md
#---------------------------------------------------------------------------
# Configuration options related to source browsing
......
if(WITH_PYTHON)
find_package(Sphinx)
if(SPHINX_EXECUTABLE)
# configured documentation tools and intermediate build results
set(BINARY_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/_build")
# Sphinx cache with pickled ReST documents
set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees")
# HTML output directory
set(SPHINX_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/html")
set(SPHINX_TITLE "${PROJECT_NAME} docs")
configure_file(
"${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in"
"${BINARY_BUILD_DIR}/conf.py"
@ONLY
)
# We add the path of the freshly build dpsim.so module to Python path here
add_custom_target(docs
COMMAND
${CMAKE_COMMAND} -E env PYTHONPATH=$<TARGET_FILE_DIR:dpsim_python>:${CMAKE_CURRENT_SOURCE_DIR}/../../Source/Python/:$ENV{PYTHONPATH}
${SPHINX_EXECUTABLE}
-q -b html
-c "${BINARY_BUILD_DIR}"
-d "${SPHINX_CACHE_DIR}"
"${CMAKE_CURRENT_SOURCE_DIR}"
"${SPHINX_HTML_DIR}"
COMMENT "Building HTML documentation with Sphinx"
DEPENDS
dpsim_python
)
endif()
endif()
\ No newline at end of file
......@@ -3,7 +3,7 @@ Reference
.. toctree::
Python
PythonModule
The core simulation kernel of DPsim is implemented in C++.
For usability, Python bindings to some of the C++ code are provided.
\ No newline at end of file
......@@ -6,7 +6,7 @@
</head>
<body>
<p>
Follow the link to the DPsim <a href="https://acs.pages.rwth-aachen.de/public/simulation/dpsim/dpsim/about.html">Sphinx documentation</a> or <a href="https://acs.pages.rwth-aachen.de/public/simulation/dpsim/dpsim/cxx/index.html">Doxygen documentation</a>.
Follow the link to the DPsim <a href="https://acs.pages.rwth-aachen.de/public/simulation/dpsim/dpsim/sphinx/about.html">Sphinx documentation</a> or <a href="https://acs.pages.rwth-aachen.de/public/simulation/dpsim/dpsim/doxygen/index.html">Doxygen documentation</a>.
</p>
</body>
</html>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment