Commit f664a607 authored by Dominik Charousset's avatar Dominik Charousset

Streamline Sphinx setup, restructure doc/ folder

(cherry picked from commit 58a477f8)
parent f15f5afc
......@@ -129,6 +129,14 @@ A SNocs workspace is provided by GitHub user
* LaTeX (for the `manual` target)
* Pandoc and Python with pandocfilters (for the `rst` target)
## Build the Manual
CAF uses [Sphinx](https://www.sphinx-doc.org):
```sh
sphinx-build . manual/html -c manual
```
## Scientific Use
If you use CAF in a scientific context, please use one of the following citations:
......
add_custom_target(doc)
# -- list all .tex source files ------------------------------------------------
set(sources
tex/Actors.tex
tex/Brokers.tex
tex/CommonPitfalls.tex
tex/ConfiguringActorApplications.tex
tex/Error.tex
tex/FAQ.tex
tex/FirstSteps.tex
tex/GroupCommunication.tex
tex/Introduction.tex
tex/ManagingGroupsOfWorkers.tex
tex/MessageHandlers.tex
tex/MessagePassing.tex
tex/Messages.tex
tex/MigrationGuides.tex
tex/NetworkTransparency.tex
tex/OpenCL.tex
tex/ReferenceCounting.tex
tex/Registry.tex
tex/RemoteSpawn.tex
tex/Scheduler.tex
tex/Streaming.tex
tex/TypeInspection.tex
tex/UsingAout.tex
tex/Utility.tex
tex/Testing.tex
)
# -- create target folders -----------------------------------------------------
file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/tex")
file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/rst")
# -- process .in files ---------------------------------------------------------
configure_file("cmake/Doxyfile.in"
"${CMAKE_CURRENT_BINARY_DIR}/Doxyfile"
@ONLY)
configure_file("cmake/variables.tex.in"
"${CMAKE_CURRENT_BINARY_DIR}/tex/variables.tex"
@ONLY)
configure_file("cmake/conf.py.in"
"${CMAKE_CURRENT_BINARY_DIR}/rst/conf.py"
@ONLY)
configure_file("cmake/index_footer.rst.in"
"${CMAKE_CURRENT_BINARY_DIR}/rst/index_footer.rst"
@ONLY)
configure_file("cmake/index_header.rst.in"
"${CMAKE_CURRENT_BINARY_DIR}/rst/index_header.rst"
@ONLY)
# -- generate .rst files -------------------------------------------------------
add_executable(caf-generate-rst cmake/caf-generate-rst.cpp)
target_link_libraries(caf-generate-rst
${CAF_EXTRA_LDFLAGS}
${CAF_LIBRARIES}
${PTHREAD_LIBRARIES})
add_custom_target(rst)
add_dependencies(doc rst)
function(convert_to_rst tex_file)
get_filename_component(file_name "${tex_file}" NAME_WE)
set(input "${CMAKE_CURRENT_SOURCE_DIR}/tex/${tex_file}")
set(rst_file "${file_name}.rst")
set(output "${CMAKE_CURRENT_BINARY_DIR}/rst/${rst_file}")
add_custom_command(OUTPUT "${output}"
COMMAND
caf-generate-rst
-o "${output}"
-i "${input}"
-r "${PROJECT_SOURCE_DIR}"
DEPENDS caf-generate-rst "${input}")
add_custom_target("${rst_file}" DEPENDS "${output}")
add_dependencies(rst "${rst_file}")
endfunction()
foreach(filename ${sources})
get_filename_component(filename_no_dir "${filename}" NAME)
convert_to_rst("${filename_no_dir}")
endforeach()
# generate index.rst file from manual.tex
add_custom_target("index.rst"
DEPENDS "tex/manual.tex"
COMMAND "python"
"${CMAKE_SOURCE_DIR}/scripts/make_index_rst.py"
"${CMAKE_CURRENT_BINARY_DIR}/rst/index.rst"
"${CMAKE_SOURCE_DIR}/doc/tex/manual.tex"
WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/rst")
add_dependencies(rst "index.rst")
# -- Doxygen setup -------------------------------------------------------------
find_package(Doxygen)
......@@ -117,21 +21,3 @@ else()
VERBATIM)
add_dependencies(doc doxygen)
endif()
# -- LaTeX setup ---------------------------------------------------------------
if (CAF_BUILD_TEX_MANUAL)
find_package(LATEX)
message(STATUS "Add optional target: manual.")
include("cmake/UseLATEX.cmake")
# enable synctex for convenient editing
set(LATEX_USE_SYNCTEX yes)
# add manual.pdf as target
add_latex_document(tex/manual.tex
INPUTS ${sources} "tex/variables.tex"
IMAGE_DIRS "pdf"
FORCE_PDF
TARGET_NAME manual)
add_dependencies(doc manual)
endif()
This diff is collapsed.
This diff is collapsed.
.. include:: index_header.rst
.. toctree::
:maxdepth: 2
:caption: Core Library
Introduction
FirstSteps
TypeInspection
MessageHandlers
Actors
MessagePassing
Scheduler
Registry
ReferenceCounting
Error
ConfiguringActorApplications
Messages
GroupCommunication
ManagingGroupsOfWorkers
Streaming
Testing
.. toctree::
:maxdepth: 2
:caption: I/O Library
NetworkTransparency
Brokers
RemoteSpawn
.. toctree::
:maxdepth: 2
:caption: Appendix
FAQ
Utility
CommonPitfalls
UsingAout
MigrationGuides
.. include:: index_footer.rst
Version Information
===================
This version of the Manual was automatically generated from CAF commit
`@CAF_SHA@ <https://github.com/actor-framework/actor-framework/commit/@CAF_SHA@>`_.
CAF User Manual
===============
**C++ Actor Framework** version @CAF_RELEASE@.
Contents
========
CAF User Manual
===============
**C++ Actor Framework** version |release|.
Contents
========
.. toctree::
:maxdepth: 2
:caption: Core Library
manual/Introduction
manual/Overview
manual/TypeInspection
manual/MessageHandlers
manual/Actors
manual/MessagePassing
manual/Scheduler
manual/Registry
manual/ReferenceCounting
manual/Error
manual/ConfiguringActorApplications
manual/Messages
manual/GroupCommunication
manual/ManagingGroupsOfWorkers
manual/Streaming
manual/Testing
.. toctree::
:maxdepth: 2
:caption: I/O Library
manual/NetworkTransparency
manual/Brokers
manual/RemoteSpawn
.. toctree::
:maxdepth: 2
:caption: Appendix
manual/FAQ
manual/Utility
manual/CommonPitfalls
manual/UsingAout
manual/MigrationGuides
......@@ -20,6 +20,34 @@
# import sys
# sys.path.insert(0, os.path.abspath('.'))
import os, sys, git, re
# Fetch the CAF version.
import re
with open("../libcaf_core/caf/config.hpp") as f:
match = re.search('^#define CAF_VERSION ([0-9]+)$', f.read(), re.MULTILINE)
if match == None:
raise RuntimeError("unable to locate CAF_VERSION string in config.hpp")
raw_version = int(match.group(1))
major = int(raw_version / 10000)
minor = int(raw_version / 100) % 100
patch = raw_version % 100
version = '{}.{}.{}'.format(major, minor, patch)
# We're building a stable release if the last commit message is
# "Change version to <version>".
repo = git.Repo(os.path.abspath('..'))
is_stable = repo.head.commit.message.startswith("Change version to " + version)
# Generate the full version, including alpha/beta/rc tags. For stable releases,
# this is always the same as the CAF version.
if is_stable:
release = version
else:
last_commit_full = str(repo.head.commit)
last_commit = last_commit_full[:7]
release = version + "+exp.sha." + last_commit
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
......@@ -47,21 +75,18 @@ source_suffix = '.rst'
# source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
master_doc = 'manual'
# General information about the project.
project = u'CAF'
copyright = u'2016, Dominik Charousset'
copyright = u'2020, Dominik Charousset'
author = u'Dominik Charousset'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = u'@CAF_VERSION@'
# The full version, including alpha/beta/rc tags.
release = u'@CAF_RELEASE@'
# Make variables available to .rst.
rst_epilog = """
.. |version| replace:: {}
.. |release| replace:: {}
""".format(version, release)
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
......@@ -157,7 +182,7 @@ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# 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']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
......
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