Commit 4c0880ee authored by Morten Ofstad's avatar Morten Ofstad
Browse files

Merge branch feature/morten.ofstad/ReCommonMarkToolDocumentation with...

Merge branch feature/morten.ofstad/ReCommonMarkToolDocumentation with refs/heads/master into refs/merge-requests/141/train
parents f7f5c1ff cc583a77
Pipeline #1880 passed with stages
in 2 minutes and 44 seconds
......@@ -21,3 +21,6 @@ python/tools/WrapperReport.txt
*.iml
java/cpp/generated
cmake-build*
/docs/tools/SEGYExport/README.md
/docs/tools/SEGYImport/README.md
/docs/tools/VDSInfo/README.md
......@@ -2,18 +2,11 @@
find_package(Doxygen REQUIRED)
find_package(Sphinx REQUIRED)
execute_process(COMMAND ${Python3_EXECUTABLE} -c "import m2r" RESULT_VARIABLE ret)
if (ret)
message(FATAL_ERROR "Missing Documentation dependency m2r. Please install Python package breath and m2r.")
endif()
execute_process(COMMAND ${Python3_EXECUTABLE} -c "import breathe" RESULT_VARIABLE ret)
if (ret)
message(FATAL_ERROR "Missing Documentation dependency breathe. Please install Python package breathe and m2r.")
endif()
# Find all the public headers
file(GLOB OPENVDS_PUBLIC_HEADERS ${PROJECT_SOURCE_DIR}/src/OpenVDS/OpenVDS/*.h)
get_target_property(OPENVDS_PUBLIC_HEADER_DIR openvds INTERFACE_INCLUDE_DIRECTORIES)
file(GLOB_RECURSE OPENVDS_PUBLIC_HEADERS ${OPENVDS_PUBLIC_HEADER_DIR}/*.h)
set(DOXYGEN_INPUT_DIRECTORY ${PROJECT_SOURCE_DIR}/src/OpenVDS)
set(DOXYGEN_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIRECTORY}/xml/index.xml)
set(DOXYGEN_GENERATE_HTML NO)
......@@ -24,9 +17,8 @@ set(DOXYGEN_EXPAND_ONLY_PREDEF YES)
set(DOXYGEN_PREDEFINED "OPENVDS_EXPORT=")
doxygen_add_docs(Doxygen
${OPENVDS_PUBLIC_HEADERS}
COMMENT "Generating docs"
)
${DOXYGEN_INPUT_DIRECTORY}
COMMENT "Generating docs")
#set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
#set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
......@@ -58,6 +50,15 @@ else ()
set(separator ";")
endif()
# Nice named target so we can run the job easily
add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})
add_dependencies(Sphinx Doxygen)
# We need to copy the README.md files into the docs folder so Sphinx can find them
add_custom_command(TARGET Sphinx PRE_BUILD COMMAND ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_CURRENT_SOURCE_DIR}/../tools/SEGYImport/README.md ${CMAKE_CURRENT_SOURCE_DIR}/tools/SEGYImport/README.md)
add_custom_command(TARGET Sphinx PRE_BUILD COMMAND ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_CURRENT_SOURCE_DIR}/../tools/SEGYExport/README.md ${CMAKE_CURRENT_SOURCE_DIR}/tools/SEGYExport/README.md)
add_custom_command(TARGET Sphinx PRE_BUILD COMMAND ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_CURRENT_SOURCE_DIR}/../tools/VDSInfo/README.md ${CMAKE_CURRENT_SOURCE_DIR}/tools/VDSInfo/README.md)
# Only regenerate Sphinx when:
# - Doxygen has rerun
# - Our doc files have been updated
......@@ -75,16 +76,11 @@ add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
${CMAKE_CURRENT_SOURCE_DIR}/getting-started.rst
${CMAKE_CURRENT_SOURCE_DIR}/python-api.rst
${CMAKE_CURRENT_SOURCE_DIR}/cpp-api.rst
${CMAKE_CURRENT_SOURCE_DIR}/tools/tools.rst
${CMAKE_CURRENT_SOURCE_DIR}/tools/segyexport_readme.rst
${CMAKE_CURRENT_SOURCE_DIR}/tools/segyimport_readme.rst
${CMAKE_CURRENT_SOURCE_DIR}/tools/vdsinfo_readme.rst
${CMAKE_CURRENT_SOURCE_DIR}/tools/SEGYImport/README.md
${CMAKE_CURRENT_SOURCE_DIR}/tools/SEGYExport/README.md
${CMAKE_CURRENT_SOURCE_DIR}/tools/VDSInfo/README.md
MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
COMMENT "Generating documentation with Sphinx")
# Nice named target so we can run the job easily
add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})
add_dependencies(Sphinx Doxygen)
# Add an install target to install the docs
install(DIRECTORY ${SPHINX_BUILD} DESTINATION ${CMAKE_INSTALL_DOCDIR})
......@@ -12,12 +12,13 @@
import os
import sys
from m2r import MdInclude
import recommonmark
from recommonmark.transform import AutoStructify
# -- Project information -----------------------------------------------------
project = 'OpenVDS'
copyright = '2020, The Open Group, 2020, Bluware, Inc.'
copyright = '2019, The Open Group, 2019, Bluware, Inc.'
author = 'Bluware'
# The full version, including alpha/beta/rc tags
......@@ -29,11 +30,18 @@ release = '0.1'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc', 'breathe']
extensions = ['sphinx.ext.autodoc', 'breathe', 'recommonmark', 'sphinx_markdown_tables']
# Breathe Configuration
breathe_default_project = 'OpenVDS'
# Recommonmark Configuration
source_parsers = {
'.md': 'CommonMarkParser',
}
source_suffix = ['.rst', '.md']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
......@@ -42,6 +50,7 @@ templates_path = ['_templates']
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
......@@ -52,12 +61,13 @@ html_theme = 'alabaster'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
#html_static_path = ['_static']
html_static_path = ['_static']
# AutoStructify Configuration
github_doc_root = 'http://osdu.pages.community.opengroup.org/platform/domain-data-mgmt-services/seismic/open-vds/'
def setup(app):
# # from m2r to make `mdinclude` work
app.add_config_value('no_underscore_emphasis', False, 'env')
app.add_config_value('m2r_parse_relative_links', False, 'env')
app.add_config_value('m2r_anonymous_references', False, 'env')
app.add_config_value('m2r_disable_inline_math', False, 'env')
app.add_directive('mdinclude', MdInclude)
app.add_config_value('recommonmark_config', {
'url_resolver': lambda url: github_doc_root + url,
'auto_toc_tree_section': 'Contents',
}, True)
app.add_transform(AutoStructify)
......@@ -15,8 +15,9 @@ Welcome to OpenVDS's documentation!
cpp-api
python-api
tools/tools
tools/SEGYImport/README.md
tools/SEGYExport/README.md
tools/VDSInfo/README.md
Indices and tables
==================
......
.. mdinclude:: ../../tools/SEGYExport/README.md
.. mdinclude:: ../../tools/SEGYImport/README.md
Tools
=====
A collection of command line utilities that can be used to create, inspect and
export a VDS. The import tool can only import from SEG-Y and export tools can
only export to SEG-Y.
.. toctree::
segyimport_readme
segyexport_readme
vdsinfo_readme
.. mdinclude:: ../../tools/VDSInfo/README.md
scikit-build
pybind11
numpy
sphinx
breathe
m2r
recommonmark
sphinx-markdown-tables
Supports Markdown
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