diff --git a/.drone.jsonnet b/.drone.jsonnet index 465c2fc6b..e30202378 100644 --- a/.drone.jsonnet +++ b/.drone.jsonnet @@ -246,6 +246,28 @@ local mac_builder(name, ], }; +local docs_pipeline(name, image, extra_cmds=[], allow_fail=false) = { + kind: 'pipeline', + type: 'docker', + name: name, + platform: { arch: 'amd64' }, + trigger: { branch: { exclude: ['debian/*', 'ubuntu/*'] } }, + steps: [ + submodules, + { + name: 'build', + image: image, + pull: 'always', + [if allow_fail then 'failure']: 'ignore', + environment: { SSH_KEY: { from_secret: 'SSH_KEY' } }, + commands: [ + 'cmake -S . -B build-docs', + 'make -C build-docs doc', + ] + extra_cmds, + }, + ], +}; + [ { @@ -324,6 +346,11 @@ local mac_builder(name, ], jobs=4), + // documentation builder + docs_pipeline('Documentation', + docker_base + 'docbuilder', + extra_cmds=['UPLOAD_OS=docs ./contrib/ci/drone-static-upload.sh']), + // integration tests debian_pipeline('Router Hive', docker_base + 'ubuntu-lts', diff --git a/contrib/ci/drone-static-upload.sh b/contrib/ci/drone-static-upload.sh index f2b445ddb..1eb8d9989 100755 --- a/contrib/ci/drone-static-upload.sh +++ b/contrib/ci/drone-static-upload.sh @@ -43,6 +43,10 @@ elif [ -e lokinet.apk ] ; then # android af ngl archive="$base.apk" cp -av lokinet.apk "$archive" +elif [ -e build-docs ]; then + archive="$base.tar.xz" + cp -a build-docs/docs/markdown "$base" + tar cJvf "$archive" "$base" else cp -av daemon/lokinet daemon/lokinet-vpn "$base" cp -av ../contrib/bootstrap/mainnet.signed "$base/bootstrap.signed" diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index c7b8a4fd5..85899e706 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -3,37 +3,70 @@ if (NOT DOXYGEN) message(STATUS "Documentation generation disabled (doxygen not found)") return() endif() -find_program(SPHINX_BUILD sphinx-build) -if (NOT SPHINX_BUILD) - message(STATUS "Documentation generation disabled (sphinx-build not found)") + +find_program(MKDOCS mkdocs) +if (NOT MKDOCS) + message(STATUS "Documentation generation disabled (mkdocs not found)") return() - endif() - +endif() + set(lokinet_doc_sources "${DOCS_SRC}") string(REPLACE ";" " " lokinet_doc_sources_spaced "${lokinet_doc_sources}") +add_custom_target(clean_xml COMMAND ${CMAKE_COMMAND} -E rm -rf doxyxml) +add_custom_target(clean_markdown COMMAND ${CMAKE_COMMAND} -E rm -rf markdown) + add_custom_command( OUTPUT doxyxml/index.xml COMMAND ${DOXYGEN} Doxyfile DEPENDS + clean_xml ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile ${lokinet_doc_sources} ) + +if(NOT DOXYBOOK2_ZIP_URL) + set(DOXYBOOK2_VERSION v1.4.0 CACHE STRING "doxybook2 version") + set(DOXYBOOK2_ZIP_URL "https://github.com/matusnovak/doxybook2/releases/download/${DOXYBOOK2_VERSION}/doxybook2-linux-amd64-${DOXYBOOK2_VERSION}.zip") + set(DOXYBOOK2_ZIP_HASH_OPTS EXPECTED_HASH SHA256=bab9356f5daa550cbf21d8d9b554ea59c8be039716a2caf6e96dee52713fccb0) +endif() + +file(DOWNLOAD + ${DOXYBOOK2_ZIP_URL} + ${CMAKE_CURRENT_BINARY_DIR}/doxybook2.zip + ${DOXYBOOK2_ZIP_HASH_OPTS}) + +execute_process(COMMAND ${CMAKE_COMMAND} -E tar xf ${CMAKE_CURRENT_BINARY_DIR}/doxybook2.zip + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}) + add_custom_command( - OUTPUT html/index.html - COMMAND ${SPHINX_BUILD} -j auto - -Dbreathe_projects.lokinet=${CMAKE_CURRENT_BINARY_DIR}/doxyxml - -Dversion=${lokinet_VERSION} -Drelease=${lokinet_VERSION} - -Aversion=${lokinet_VERSION} -Aversions=${lokinet_VERSION_MAJOR},${lokinet_VERSION_MINOR},${lokinet_VERSION_PATCH} - -b html - ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}/html + OUTPUT markdown + COMMAND ${CMAKE_CURRENT_BINARY_DIR}/bin/doxybook2 --input ${CMAKE_CURRENT_BINARY_DIR}/doxyxml --output ${CMAKE_CURRENT_BINARY_DIR}/markdown --config config.json DEPENDS - ${CMAKE_CURRENT_BINARY_DIR}/index.rst - ${CMAKE_CURRENT_BINARY_DIR}/conf.py - ${CMAKE_CURRENT_BINARY_DIR}/doxyxml/index.xml -) -add_custom_target(doc DEPENDS html/index.html) -configure_file(conf.py.in conf.py @ONLY) + ${CMAKE_CURRENT_BINARY_DIR}/markdown/index.md + ${CMAKE_CURRENT_BINARY_DIR}/config.json + ${CMAKE_CURRENT_BINARY_DIR}/bin/doxybook2 + ${CMAKE_CURRENT_BINARY_DIR}/doxyxml/index.xml) + +add_custom_target(clean_html COMMAND ${CMAKE_COMMAND} -E rm -rf html) + +add_custom_command( + OUTPUT html + COMMAND ${MKDOCS} build + DEPENDS + clean_html + ${CMAKE_CURRENT_BINARY_DIR}/markdown) + +add_custom_target(doc DEPENDS html) + +# we seperate this step out so we force clean_markdown to run before markdown target +add_custom_command( + OUTPUT markdown/index.md + COMMAND ${CMAKE_COMMAND} -E copy index.md markdown/index.md + DEPENDS clean_markdown) + configure_file(Doxyfile.in Doxyfile @ONLY) -configure_file(index.rst index.rst COPYONLY) +configure_file(config.json config.json @ONLY) +configure_file(mkdocs.yml mkdocs.yml @ONLY) +configure_file(index.md.in index.md @ONLY) diff --git a/docs/conf.py.in b/docs/conf.py.in deleted file mode 100644 index e99ba91ec..000000000 --- a/docs/conf.py.in +++ /dev/null @@ -1,189 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Configuration file for the Sphinx documentation builder. -# -# This file does only contain a selection of the most common options. For a -# full list see the documentation: -# http://www.sphinx-doc.org/en/master/config - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - - -# -- Project information ----------------------------------------------------- - -project = 'lokinet' -copyright = '2020, Jeff Becker' -author = 'Jeff Becker' - -# The short X.Y version -version = '' -# The full version, including alpha/beta/rc tags -release = '' - - - -# -- General configuration --------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. - -extensions = ['breathe', 'exhale'] -breathe_projects = { "lokinet": "@CMAKE_CURRENT_BINARY_DIR@/doxyxml/" } -breathe_default_project = "lokinet" -breathe_domain_by_extension = {"h" : "cpp", "hpp": "cpp"} - -exhale_args = { - # These arguments are required - "containmentFolder": "./api", - "rootFileName": "lokinet.rst", - "rootFileTitle": "lokinet internals", - "doxygenStripFromPath": "..", - # Suggested optional arguments - "createTreeView": True, - # TIP: if using the sphinx-bootstrap-theme, you need - # "treeViewIsBootstrap": True, -} - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -source_suffix = ['.rst', '.md'] - -# The master toctree document. -master_doc = 'index' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' -highlight_language = 'c++' -primary_domain = 'cpp' -default_role = 'cpp:any' -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'sphinx_rtd_theme' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# 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'] - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# The default sidebars (for documents that don't match any pattern) are -# defined by theme itself. Builtin themes are using these templates by -# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', -# 'searchbox.html']``. -# -# html_sidebars = {} - - -# -- Options for HTMLHelp output --------------------------------------------- - -# Output file base name for HTML help builder. -htmlhelp_basename = 'lokinetdoc' - - -# -- Options for LaTeX output ------------------------------------------------ - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'lokinet.tex', 'lokinet Documentation', - 'Jeff Becker', 'manual'), -] - - -# -- Options for manual page output ------------------------------------------ - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'lokinet', 'lokinet Documentation', - [author], 1) -] - - -# -- Options for Texinfo output ---------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'lokinet', 'lokinet Documentation', - author, 'lokinet', 'One line description of project.', - 'Miscellaneous'), -] - - -# -- Options for Epub output ------------------------------------------------- - -# Bibliographic Dublin Core info. -epub_title = project - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -# -# epub_identifier = '' - -# A unique identification for the text. -# -# epub_uid = '' - -# A list of files that should not be packed into the epub file. -epub_exclude_files = ['search.html'] diff --git a/docs/config.json b/docs/config.json new file mode 100644 index 000000000..660ff8d8b --- /dev/null +++ b/docs/config.json @@ -0,0 +1,9 @@ +{ + "baseUrl": "/internals/", + "indexInFolders": false, + "linkSuffix": "/", + "mainPageInRoot": false, + "mainPageName": "index", + "linkLowercase": true, + "foldersToGenerate": ["files", "classes", "namespaces"] +} diff --git a/docs/index.md.in b/docs/index.md.in new file mode 100644 index 000000000..d7fe69d00 --- /dev/null +++ b/docs/index.md.in @@ -0,0 +1,7 @@ +# Lokinet @lokinet_VERSION@ (git rev: @GIT_VERSION@) + +summary goes here + +## Overview + +[code internals](index_namespaces.md) diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index a58c3ac24..000000000 --- a/docs/index.rst +++ /dev/null @@ -1,8 +0,0 @@ - -Welcome to Lokinet Internals -============================ - -.. toctree:: - :maxdepth: 2 - - api/lokinet diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 000000000..6a7e73926 --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,7 @@ +site_name: Lokinet +theme: + name: 'readthedocs' +markdown_extensions: + - admonition +docs_dir: markdown +site_dir: html