xo-ratio: docs: initial doxygen+sphinx scaffold
This commit is contained in:
parent
75f78b45d3
commit
06e230ebfd
9 changed files with 3247 additions and 1 deletions
|
|
@ -58,7 +58,7 @@ xo_toplevel_compile_options()
|
|||
|
||||
add_subdirectory(example)
|
||||
add_subdirectory(utest)
|
||||
#add_subdirectory(docs)
|
||||
add_subdirectory(docs)
|
||||
|
||||
# ----------------------------------------------------------------
|
||||
# provide find_package() support for projects using this library
|
||||
|
|
|
|||
118
docs/CMakeLists.txt
Normal file
118
docs/CMakeLists.txt
Normal file
|
|
@ -0,0 +1,118 @@
|
|||
# xo-ratio/docs/CMakeLists.txt
|
||||
|
||||
if (XO_SUBMODULE_BUILD)
|
||||
# in submodule build, rely on toplevel docs/CMakeLists.txt file instead
|
||||
else()
|
||||
# build docs starting from here only in standalone build.
|
||||
# otherwise use top-level doxygen setup instead.
|
||||
|
||||
set(ALL_LIBRARY_TARGETS xo_ratio) # todo: automate this from xo-cmake macros
|
||||
set(ALL_UTEST_TARGETS utest.ratio xo_ratio_ex1 ) # todo: automate this from xo-cmake macros
|
||||
|
||||
# look for doxygen executable
|
||||
find_program(DOXYGEN_EXECUTABLE NAMES doxygen REQUIRED)
|
||||
message("-- DOXYGEN_EXECUTABLE=${DOXYGEN_EXECUTABLE}")
|
||||
|
||||
# look for sphinx-build executable
|
||||
find_program(SPHINX_EXECUTABLE NAMES sphinx-build REQUIRED)
|
||||
message("-- SPHINX_EXECUTABLE=${SPHINX_EXECUTABLE}")
|
||||
|
||||
set(DOX_CONFIG_FILE ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
|
||||
|
||||
set(DOX_INPUT_DIR ${PROJECT_SOURCE_DIR})
|
||||
set(DOX_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/dox)
|
||||
|
||||
set(DOX_INDEX_FILE ${DOX_OUTPUT_DIR}/html/index.html)
|
||||
|
||||
# .hpp files reachable from xo-ratio/include
|
||||
#
|
||||
# REMINDER: for reliability will need to re-run cmake when the set of .hpp files changes
|
||||
#
|
||||
file(GLOB_RECURSE DOX_HPP_FILES_GLOB ${PROJECT_SOURCE_DIR}/include *.hpp)
|
||||
|
||||
set(SPHINX_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/sphinx/html)
|
||||
set(SPHINX_INDEX_FILE ${SPHINX_OUTPUT_DIR}/index.html)
|
||||
#
|
||||
# sphinx .rst files reachable from cmake-examples/docs
|
||||
#
|
||||
# REMINDER: for reliability will need to re-run cmake when the set of .rst files changes
|
||||
#
|
||||
file(GLOB_RECURSE SPHINX_RST_FILES_GLOB ${CMAKE_CURRENT_SOURCE_DIR} *.rst)
|
||||
|
||||
set(SPHINX_RST_FILES index.rst
|
||||
#install.rst
|
||||
#lessons.rst
|
||||
#flatstring-reference.rst
|
||||
#flatstring-class.rst
|
||||
)
|
||||
|
||||
# TODO:
|
||||
# 1. move Doxyfile.in to xo-cmake project
|
||||
# 2. replace this command section with xo-cmake macro
|
||||
#
|
||||
configure_file(
|
||||
Doxyfile.in ${DOX_CONFIG_FILE}
|
||||
FILE_PERMISSIONS OWNER_READ OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE
|
||||
@ONLY)
|
||||
|
||||
set(DOX_DEPS ${ALL_LIBRARY_TARGETS} ${ALL_UTEST_TARGETS} ${DOX_HPP_FILES_GLOB})
|
||||
|
||||
file(MAKE_DIRECTORY ${DOX_OUTPUT_DIR})
|
||||
add_custom_command(
|
||||
OUTPUT ${DOX_INDEX_FILE}
|
||||
DEPENDS ${DOX_DEPS}
|
||||
COMMAND "${DOXYGEN_EXECUTABLE}" ${DOX_CONFIG_FILE}
|
||||
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
|
||||
MAIN_DEPENDENCY ${DOX_CONFIG_FILE}
|
||||
COMMENT "Generating docs (doxygen)")
|
||||
|
||||
# To build this target
|
||||
# $ cmake --build .build -j -- doxygen
|
||||
# or
|
||||
# $ cd .build
|
||||
# $ make doxygen
|
||||
#
|
||||
add_custom_target(
|
||||
doxygen
|
||||
DEPENDS ${DOX_INDEX_FILE} ${DOX_DEPS}
|
||||
)
|
||||
|
||||
# root of sphinx doc tree
|
||||
set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
|
||||
set(SPHINX_DEPS doxygen conf.py ${SPHINX_RST_FILES} ${SPHINX_RST_FILES_GLOB} ${DOX_DEPS})
|
||||
|
||||
add_custom_command(
|
||||
OUTPUT ${SPHINX_INDEX_FILE}
|
||||
DEPENDS ${SPHINX_DEPS}
|
||||
COMMAND ${SPHINX_EXECUTABLE}
|
||||
-b html -Dbreathe_projects.xodoxxml=${CMAKE_CURRENT_BINARY_DIR}/dox/xml
|
||||
${SPHINX_SOURCE} ${SPHINX_OUTPUT_DIR}
|
||||
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
|
||||
COMMENT "Generating docs (sphinx) -> [${SPHINX_OUTPUT_DIR}]")
|
||||
|
||||
# make sphinx --> generate sphinx documentation
|
||||
#
|
||||
add_custom_target(
|
||||
sphinx
|
||||
DEPENDS ${SPHINX_INDEX_FILE})
|
||||
|
||||
# - html docs generated in build/docs/sphinx
|
||||
# - copy the doc tree to share/doc/xo_unit/html
|
||||
#
|
||||
# DESTINATION: CMAKE_INSTALL_DOCDIR
|
||||
# => DATAROOTDIR/doc/PROJECT_NAME
|
||||
# => CMAKE_INSTALL_PREFIX/share/doc/xo_flatstring
|
||||
# OPTIONAL: install directory tree if it exists,
|
||||
# but don't complain if it's missing
|
||||
install(
|
||||
DIRECTORY ${SPHINX_OUTPUT_DIR}
|
||||
FILE_PERMISSIONS OWNER_READ GROUP_READ WORLD_READ
|
||||
DESTINATION ${CMAKE_INSTALL_DOCDIR}
|
||||
COMPONENT Documentation
|
||||
OPTIONAL)
|
||||
|
||||
# make docs --> generate sphinx documentation
|
||||
add_custom_target(
|
||||
docs
|
||||
DEPENDS sphinx)
|
||||
endif()
|
||||
2816
docs/Doxyfile.in
Normal file
2816
docs/Doxyfile.in
Normal file
File diff suppressed because it is too large
Load diff
BIN
docs/_static/img/favicon.ico
vendored
Normal file
BIN
docs/_static/img/favicon.ico
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 302 KiB |
77
docs/_static/img/icon.svg
vendored
Normal file
77
docs/_static/img/icon.svg
vendored
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<!-- Created with Inkscape (http://www.inkscape.org/) -->
|
||||
|
||||
<svg
|
||||
width="108.32474mm"
|
||||
height="108.39381mm"
|
||||
viewBox="0 0 108.32474 108.39382"
|
||||
version="1.1"
|
||||
id="svg5"
|
||||
inkscape:version="1.1.2 (0a00cf5339, 2022-02-04)"
|
||||
sodipodi:docname="icon.svg"
|
||||
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
|
||||
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
|
||||
xmlns="http://www.w3.org/2000/svg"
|
||||
xmlns:svg="http://www.w3.org/2000/svg">
|
||||
<sodipodi:namedview
|
||||
id="namedview7"
|
||||
pagecolor="#ffffff"
|
||||
bordercolor="#666666"
|
||||
borderopacity="1.0"
|
||||
inkscape:pageshadow="2"
|
||||
inkscape:pageopacity="0.0"
|
||||
inkscape:pagecheckerboard="0"
|
||||
inkscape:document-units="mm"
|
||||
showgrid="false"
|
||||
inkscape:zoom="1"
|
||||
inkscape:cx="157"
|
||||
inkscape:cy="322.5"
|
||||
inkscape:window-width="1607"
|
||||
inkscape:window-height="1085"
|
||||
inkscape:window-x="26"
|
||||
inkscape:window-y="23"
|
||||
inkscape:window-maximized="0"
|
||||
inkscape:current-layer="layer1"
|
||||
fit-margin-top="9.8"
|
||||
fit-margin-left="8"
|
||||
fit-margin-right="10"
|
||||
fit-margin-bottom="9.8" />
|
||||
<defs
|
||||
id="defs2" />
|
||||
<g
|
||||
inkscape:label="Layer 1"
|
||||
inkscape:groupmode="layer"
|
||||
id="layer1"
|
||||
transform="translate(-47.453609,-27.112369)">
|
||||
<circle
|
||||
style="fill:#ff0000;fill-rule:evenodd;stroke-width:0.264583"
|
||||
id="path31"
|
||||
cx="68.211342"
|
||||
cy="87.603088"
|
||||
r="12.757732" />
|
||||
<circle
|
||||
style="fill:#ffcf00;fill-opacity:1;fill-rule:evenodd;stroke-width:0.264583"
|
||||
id="path31-3"
|
||||
cx="122.47422"
|
||||
cy="49.670101"
|
||||
r="12.757732" />
|
||||
<circle
|
||||
style="fill:#6b6bff;fill-opacity:1;fill-rule:evenodd;stroke-width:0.264583"
|
||||
id="path31-3-6"
|
||||
cx="133.02061"
|
||||
cy="112.94845"
|
||||
r="12.757732" />
|
||||
<path
|
||||
style="fill:none;stroke:#000000;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
|
||||
d="M 73.144329,75.525772 C 85.051544,48.309278 109.54639,49.670102 109.54639,49.670102"
|
||||
id="path589" />
|
||||
<path
|
||||
style="fill:none;stroke:#000000;stroke-width:2.44548;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
|
||||
d="M 76.544292,96.598799 C 95.429921,116.11457 120.4897,113.37017 120.4897,113.37017"
|
||||
id="path593" />
|
||||
<path
|
||||
style="fill:none;stroke:#000000;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
|
||||
d="m 132,58.175257 c 17.01031,17.350515 7.14433,43.886603 7.14433,43.886603"
|
||||
id="path788" />
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 2.7 KiB |
77
docs/_static/img/xo-icon.svg
vendored
Normal file
77
docs/_static/img/xo-icon.svg
vendored
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<!-- Created with Inkscape (http://www.inkscape.org/) -->
|
||||
|
||||
<svg
|
||||
width="108.32474mm"
|
||||
height="108.39381mm"
|
||||
viewBox="0 0 108.32474 108.39382"
|
||||
version="1.1"
|
||||
id="svg5"
|
||||
inkscape:version="1.1.2 (0a00cf5339, 2022-02-04)"
|
||||
sodipodi:docname="xo-icon.svg"
|
||||
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
|
||||
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
|
||||
xmlns="http://www.w3.org/2000/svg"
|
||||
xmlns:svg="http://www.w3.org/2000/svg">
|
||||
<sodipodi:namedview
|
||||
id="namedview7"
|
||||
pagecolor="#ffffff"
|
||||
bordercolor="#666666"
|
||||
borderopacity="1.0"
|
||||
inkscape:pageshadow="2"
|
||||
inkscape:pageopacity="0.0"
|
||||
inkscape:pagecheckerboard="0"
|
||||
inkscape:document-units="mm"
|
||||
showgrid="false"
|
||||
inkscape:zoom="1"
|
||||
inkscape:cx="157"
|
||||
inkscape:cy="322.5"
|
||||
inkscape:window-width="1607"
|
||||
inkscape:window-height="1085"
|
||||
inkscape:window-x="26"
|
||||
inkscape:window-y="23"
|
||||
inkscape:window-maximized="0"
|
||||
inkscape:current-layer="layer1"
|
||||
fit-margin-top="9.8"
|
||||
fit-margin-left="8"
|
||||
fit-margin-right="10"
|
||||
fit-margin-bottom="9.8" />
|
||||
<defs
|
||||
id="defs2" />
|
||||
<g
|
||||
inkscape:label="Layer 1"
|
||||
inkscape:groupmode="layer"
|
||||
id="layer1"
|
||||
transform="translate(-47.453609,-27.112369)">
|
||||
<circle
|
||||
style="fill:#ff0000;fill-rule:evenodd;stroke-width:0.264583"
|
||||
id="path31"
|
||||
cx="68.211342"
|
||||
cy="87.603088"
|
||||
r="12.757732" />
|
||||
<circle
|
||||
style="fill:#ffcf00;fill-opacity:1;fill-rule:evenodd;stroke-width:0.264583"
|
||||
id="path31-3"
|
||||
cx="122.47422"
|
||||
cy="49.670101"
|
||||
r="12.757732" />
|
||||
<circle
|
||||
style="fill:#6b6bff;fill-opacity:1;fill-rule:evenodd;stroke-width:0.264583"
|
||||
id="path31-3-6"
|
||||
cx="133.02061"
|
||||
cy="112.94845"
|
||||
r="12.757732" />
|
||||
<path
|
||||
style="fill:none;stroke:#000000;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
|
||||
d="M 73.144329,75.525772 C 85.051544,48.309278 109.54639,49.670102 109.54639,49.670102"
|
||||
id="path589" />
|
||||
<path
|
||||
style="fill:none;stroke:#000000;stroke-width:2.44548;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
|
||||
d="M 76.544292,96.598799 C 95.429921,116.11457 120.4897,113.37017 120.4897,113.37017"
|
||||
id="path593" />
|
||||
<path
|
||||
style="fill:none;stroke:#000000;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
|
||||
d="m 132,58.175257 c 17.01031,17.350515 7.14433,43.886603 7.14433,43.886603"
|
||||
id="path788" />
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 2.7 KiB |
36
docs/conf.py
Normal file
36
docs/conf.py
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# For the full list of built-in configuration values, see the documentation:
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
|
||||
|
||||
project = 'xo ratio documentation'
|
||||
copyright = '2024, Roland Conybeare'
|
||||
author = 'Roland Conybeare'
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
|
||||
|
||||
#extensions = []
|
||||
extensions = [ "breathe",
|
||||
"sphinx.ext.autodoc" # generate info from docstrings
|
||||
]
|
||||
|
||||
# note: breathe requires doxygen xml output -> must have GENERATE_XML = YES in Doxyfile.in
|
||||
# match project name in Doxyfile.in
|
||||
breathe_default_project = "xodoxxml"
|
||||
|
||||
templates_path = ['_templates']
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
pygments_style = 'sphinx'
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
|
||||
|
||||
#html_theme = 'alabaster'
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
html_static_path = ['_static']
|
||||
html_favicon = '_static/img/favicon.ico'
|
||||
34
docs/index.rst
Normal file
34
docs/index.rst
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
|
||||
xo-ratio documentation
|
||||
======================
|
||||
|
||||
xo-ratio is a lightweight header-only library that provides a constexpr
|
||||
fixed-size no-allocation ratio implementation.
|
||||
|
||||
Why ``ratio``?
|
||||
|
||||
1. ``ratio`` instances can be used as template arguments. [1]_
|
||||
|
||||
2. ``ratio`` operations (arithmetic, integer powers, string conversion, ...) are ``constexpr``, so can be done at compile time. [2]_
|
||||
|
||||
3. a ``ratio`` expression can occupy both compile-time and runtime roles. [3]_
|
||||
|
||||
.. [1] verified with gcc 13.2.0; clang 18 does not recognize ratio<T> as a structured type for some reason.
|
||||
|
||||
.. [2] Although allocation is permitted in constexpr code, it's subject to several restrictions.
|
||||
it's not yet possible (as of c++23) to use ``std::string`` at compile time.
|
||||
Using ``xo::flatstring`` instead.
|
||||
|
||||
.. [3] contrast with a solution relying on template arguments, which must then be compile-time-only.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: xo-ratio contents:
|
||||
|
||||
install
|
||||
|
||||
Indices and Tables
|
||||
------------------
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`search`
|
||||
88
docs/install.rst
Normal file
88
docs/install.rst
Normal file
|
|
@ -0,0 +1,88 @@
|
|||
.. _install:
|
||||
|
||||
.. toctree
|
||||
:maxdepth: 2
|
||||
|
||||
Source
|
||||
======
|
||||
|
||||
Source code lives on github `here`_
|
||||
|
||||
.. _here: https://github.com/rconybea/xo-ratio
|
||||
|
||||
To clone from git:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git clone https://github.com/rconybea/xo-ratio
|
||||
|
||||
Implementation relies on c++20 features (expanded use of constexpr; class-instances as template arguments).
|
||||
Tested with gcc 13.2
|
||||
|
||||
Install
|
||||
=======
|
||||
|
||||
Since xo-ratio is header-only, can incorporate into another project just by copying the include directories
|
||||
to somewhere convenient.
|
||||
|
||||
Copy includes
|
||||
-------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# For example..
|
||||
cd myproject
|
||||
mkdir -p ext/xo-ratio
|
||||
rsync -a -v path/to/xo-ratio/include/ ext/xo-ratio/
|
||||
|
||||
Include as git submodule
|
||||
------------------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd myproject
|
||||
git submodule add -b main https://github.com/rconybea/xo-ratio ext/xo-ratio
|
||||
git submodule update --init
|
||||
|
||||
This assumes you organize directly-incorporated dependencies under directory ``myproject/ext``.
|
||||
You would then add ``myproject/ext/xo-ratio/include`` to your compiler's include path,
|
||||
and from c++ do something like
|
||||
|
||||
.. code-block:: c++
|
||||
|
||||
#include <xo/ratio/ratio.hpp>
|
||||
|
||||
in c++ source files that rely on xo-ratio
|
||||
|
||||
Supported compilers
|
||||
-------------------
|
||||
|
||||
* developed with gcc 13.2.0; github CI using gcc 11.4.0 (asof April 2024)
|
||||
|
||||
Building from source
|
||||
--------------------
|
||||
|
||||
Although the xo-ratio library is header-only, unit tests have some dependencies.
|
||||
Example instructions (github CI) for build starting from stock ubuntu are in `ubuntu-main.yml`_
|
||||
|
||||
.. _ubuntu-main.yml: https://github.com/Rconybea/xo-ratio/blob/main/.github/workflows/ubuntu-main.yml
|
||||
|
||||
Unit test dependencies:
|
||||
|
||||
* `catch2`_ header-only unit-test framework
|
||||
* `xo-cmake`_ cmake macros
|
||||
* `xo-indentlog`_ logging with call-structure indenting
|
||||
* `xo-randomgen`_ fast random-number generator (xoshiro256ss)
|
||||
|
||||
.. _catch2: https://github.com/catchorg/Catch2
|
||||
.. _xo-cmake: https://github.com/rconybea/xo-cmake
|
||||
.. _xo-indentlog: https://github.com/rconybea/indentlog
|
||||
.. _xo-randomgen: https://github.com/rconybea/randomgen
|
||||
|
||||
To build documentation, will also need:
|
||||
|
||||
* `doxygen`
|
||||
* `graphviz`
|
||||
* `sphinx`
|
||||
* `breathe`
|
||||
* `sphinx_rtd_theme`
|
||||
Loading…
Add table
Add a link
Reference in a new issue