Documentation

[thamnos]

I'm testing sphinx to document sassena. An empty (but working) version can be found here
https://thamnos.github.io/sassena/
which is automatically generated when running "make gh-pages" in the docs directory of
https://github.com/thamnos/sassena/tree/using_sphinx_documentation
Any comments? I'd otherwise start to fill it with content soon...

[jmborr]

It's a great idea, but using cmake would be the preferred way to end up with a Makefile.

I could add you as collaborator of camm/sassena . Let me know if you prefer that to having a fork of the project.

A FindSphinx.cmake file could be placed under subdirectory cmake/modules/:

find_program(SPHINX_EXECUTABLE NAMES sphinx-build
    HINTS ENV $ENV{SPHINX_DIR}
    PATH_SUFFIXES bin
    DOC "Sphinx documentation generator"
)
include(FindPackageHandleStandardArgs)
find_package_handle_standard_args(Sphinx DEFAULT_MSG SPHINX_EXECUTABLE)
mark_as_advanced(SPHINX_EXECUTABLE)

These lines could be added to the main CMakeLists.txt:

# compile the docs
add_subdirectory(docs)

And a crude CMakeLists.txt under the docs/ to generate the target:

find_package(Sphinx REQUIRED)
if(NOT DEFINED SPHINX_THEME)
    set(SPHINX_THEME default)
endif()
if(NOT DEFINED SPHINX_THEME_DIR)
    set(SPHINX_THEME_DIR)
endif()
# 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")
configure_file(
    "${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in"
    "${BINARY_BUILD_DIR}/conf.py"
    @ONLY)
add_custom_target(htmldocs ALL
    ${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")

I got all this from https://eb2.co/blog/2012/03/sphinx-and-cmake-beautiful-documentation-for-c-projects/ 😀

[thamnos]

Being a collaborator of camm/sassena would be handy, thank you!
I might experiment a bit more with sphinx on thamnos/sassena but once I've figured it out a bit more, it would be great to contribute here directly.

I've read a bit about sphinx & cmake... let me try to summarize what I think I understand so far:

• sphinx can be used to write the user documentation in reStructuredText, including maths. The output can be many formats, e.g. pdf and html. If html is generated and either placed in a branch "gh-pages" or in the docs directory of the main branch, github can display it directly as a homepage "github-pages" like on https://thamnos.github.io/sassena/
• sphinx can also be used to document the source code, for example by coupling it with doxygen using https://github.com/michaeljones/breathe

If one wants the documentation to be displayed by github-pages (which I think is very handy), it has to be built and pushed by the developer, the user does not have to have sphinx/latex installed as the reStructuredText is already converted to pdf & html.
It seems to me that for both places for the html pages to be displayed in github-pages, the gh-pages branch and docs folder, some manual work is needed to make it work -- the easiest maybe being this one
sphinx-doc/sphinx#3382
where the documents are placed in the docs folder and the subdirectories that sphinx wants them to be and to add a redirect html page at the place where github-pages wants an index.html to be. This should be a one-off edit in contrast to many other methods that require moving the generated output from its build directory to the right place for github-pages.

I'll let you know how I'm getting on with this & the change from the sphinx-supplied Makefile to cmake.
Some more things I found concerning the latter:
https://github.com/cmake-basis/find-modules/blob/master/FindSphinx.cmake
https://gitlab.kitware.com/cmake/cmake/commit/bfe07aa97efdd0c9a5fb9eb7adc0a1a166149711

Best,
Sebastian.