Commit 056c427d authored by Alberto Miranda's avatar Alberto Miranda ♨️
Browse files

Merge branch 'amiranda/159-generate-doxygen-documentation' into 'master'

Resolve "Automatically generate GekkoFS documentation"

This MR adds a `docs` target to the build system that can be used to automatically generate Sphinx documentation based on ReStructured Text for the project. Additionally, it also processes the source files through Doxygen to generate intermediate XML that can be passed to Sphinx extensions Breathe and Exhale so that GekkoFS classes and functions can be referenced from the Sphinx documentation.

The CI script is also extended to build this documentation and deploy it to the project's site.

Closes #159

See merge request !95
parents fd648a01 3f498869
Loading
Loading
Loading
Loading
Loading
+62 −0
Original line number Diff line number Diff line
@@ -2,7 +2,9 @@ stages:
  - lint
  - build
  - test
  - docs
  - report
  - deploy

variables:
  SCRIPTS_DIR:                  "${CI_PROJECT_DIR}/scripts"
@@ -233,6 +235,42 @@ gkfs:unit:
      junit: ${BUILD_PATH}/tests/unit/report.xml


################################################################################
## Generation of documentation
################################################################################
documentation:
  stage: docs
  image: gekkofs/docs:0.9.0
  needs: []
  rules:
    # we only build the documentation automatically if we are on the
    # `master` branch, but since we also would like to test the documentation
    # against our CI, we allow developers to also build it manually
    - if: '$CI_MERGE_REQUEST_EVENT_TYPE == "detached"'
      when: never
    - if: '$CI_MERGE_REQUEST_ID != ""'
      when: manual
      allow_failure: true
    - if: '$CI_COMMIT_REF_SLUG == "master"'
      when: always

  script:
    - mkdir -p ${BUILD_PATH} && cd ${BUILD_PATH}
    - cmake
      -Wdev
      -Wdeprecate
      -DCMAKE_BUILD_TYPE=Debug
      -DGKFS_BUILD_DOCUMENTATION:BOOL=ON
      -DCMAKE_PREFIX_PATH=${DEPS_INSTALL_PATH}
      -DCMAKE_INSTALL_PREFIX=${INSTALL_PATH}
      ${CI_PROJECT_DIR}
    - make docs
  artifacts:
    paths:
      - ${BUILD_PATH}/docs
    expire_in: 2 weeks


################################################################################
## Generation of code coverage reports
################################################################################
@@ -254,3 +292,27 @@ coverage:
    paths:
      - ${BUILD_PATH}/.coverage
    expire_in: 2 weeks


################################################################################
## Deployment of documentation and reports
################################################################################
#
## for the deploy stage to work as expected, we need to run rsync with the
## appropriate credentials provided by sysadmins. For that, the specific values
## for DEPLOY_KEY_FILE, DEPLOY_USERNAME, DEPLOY_GROUP, DEPLOY_SERVER and
## DEPLOY_PATH must be defined as protected variables.
deploy:
  image: bscstorage/deployer
  stage: deploy
  needs: [ 'documentation' ]
  only:
    - master
  script:
    - chmod 400 ${DEPLOY_KEY_FILE}
    - rsync -e "ssh -i ${DEPLOY_KEY_FILE}"
        -avzr
        --delete
        --chown=${DEPLOY_USERNAME}:${DEPLOY_GROUP}
        ${BUILD_PATH}/docs/sphinx/sphinx_docs/
        ${DEPLOY_USERNAME}@${DEPLOY_SERVER}:${DEPLOY_PATH}

CMake/FindSphinx.cmake

0 → 100644
+629 −0

File added.

Preview size limit exceeded, changes collapsed.

+8 −0
Original line number Diff line number Diff line
@@ -140,6 +140,14 @@ find_package(Date REQUIRED)
# Import some convenience functions
include(gkfs-utils)

################################################################################
## Build GekkoFS documentation
################################################################################
option(GKFS_BUILD_DOCUMENTATION "Build documentation" OFF)
if(GKFS_BUILD_DOCUMENTATION)
  add_subdirectory(docs)
endif()

option(CREATE_CHECK_PARENTS "Check parent directory existance before creating child node" ON)
message(STATUS "[gekkofs] Create checks parents: ${CREATE_CHECK_PARENTS}")

+33 −0
Original line number Diff line number Diff line
FROM gekkofs/deps:0.8.0

LABEL Description="Debian-based environment suitable to build GekkoFS' documentation"

RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        # install dependencies for Doxygen
        python \
        flex \
        bison \
		graphviz && \
	# install doxygen (repo version is kind of old)
	cd /tmp && curl -OL https://www.doxygen.nl/files/doxygen-1.9.2.src.tar.gz && \
	tar xvfz /tmp/doxygen-1.9.2.src.tar.gz && \
	mkdir -p /tmp/doxygen-1.9.2/build && \
	cd /tmp/doxygen-1.9.2/build && \
	cmake -G "Unix Makefiles" .. && \
	make -j8 install && \
    # install sphinx, breathe and exhale
    pip3 install \
        'sphinx==4.4.0' \
        sphinx_rtd_theme \
        'breathe==4.31.0' \
        'exhale==0.2.4' \
        'sphinx-copybutton==0.4.0' \
        'sphinx-multiversion==0.2.4' \
        'myst_parser==0.15.1' && \
    # Clean apt cache to reduce image layer size
    rm -rf /var/lib/apt/lists/* && \
    rm -rf /tmp/doxygen-1.9.2 && \
    rm /tmp/doxygen-1.9.2.src.tar.gz && \
    # Clean apt caches of packages
    apt-get clean && apt-get autoclean
+4 −0
Original line number Diff line number Diff line
.PHONY: all

all:
	docker build -t gekkofs/docs:0.8.0 .
Loading