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

.gitlab-ci.yml

+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.

CMakeLists.txt

+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}")

docker/0.8.0/docs/Dockerfile

0 → 100644
+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

docker/0.8.0/docs/Makefile

0 → 100644
+4 −0
Original line number Diff line number Diff line 
.PHONY: all



all:

	docker build -t gekkofs/docs:0.8.0 .