Commit 57d15640 authored by Andrei Muresan's avatar Andrei Muresan
Browse files

Merge branch 'feature/doc-generation' into 'master'

Feature: doc generation

See merge request !3
parents f39f3cd8 7409a6ed
Pipeline #27938 failed with stages
in 59 seconds
ntp
bin
lib
obj
......@@ -7,4 +7,5 @@ build
*.log
ntp
bin
lib
\ No newline at end of file
lib
public
stages:
- lint
- build
- docs
- publish
variables:
DOCGEN_IMAGE: "$CI_REGISTRY/phaar/$CI_PROJECT_NAME/docgen"
# Checks code formatting & style
lint:
stage: lint
tags:
......@@ -8,4 +15,52 @@ lint:
image: "alpine:latest"
script:
- apk add make clang
- ./scripts/ci-lint.sh
\ No newline at end of file
- ./scripts/ci-lint.sh
# Builds & publishes container image used for doc generation to the project's container registry
build:docgen_image:
stage: build
tags:
- docker-runner
image: docker
services:
- docker:dind
script:
- docker build -t "$DOCGEN_IMAGE:$CI_COMMIT_REF_SLUG" -f Dockerfile.docgen .
- docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY"
- docker push "$DOCGEN_IMAGE:$CI_COMMIT_REF_SLUG"
rules:
- changes:
- Dockerfile.docgen
# Generates docs and stashes the resulting artifacts
docs:generate:
stage: docs
environment:
name: "review/$CI_COMMIT_REF_NAME"
url: "https://$phaar.pages.triumf.ca/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html"
variables:
PUBLIC_URL: "/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public"
tags:
- docker-runner
image:
name: "$DOCGEN_IMAGE"
entrypoint: [""]
script:
- make docs
artifacts:
paths:
- 'public'
# Publishes generated docs to GitLab Pages (only from master branch)
pages:
stage: publish
tags:
- docker-runner
image: alpine:latest
script:
- '[ -d public ] || exit 1'
dependencies:
- docs:generate
rules:
- if: '$CI_COMMIT_BRANCH == "master"'
# This container image is used in the pipeline to export documentation
#
# The image is in the vanwftk project's container registry under the name
# "registry.triumf.ca/phaar/vanwftk/docgen"
FROM think/plantuml:1.2020.5
LABEL maintainer="andrei@muresan.io"
RUN apk add --no-cache make doxygen graphviz
ENV PLANTUML_JAR_PATH='/plantuml.jar'
WORKDIR /vanwftk
ENTRYPOINT ["/bin/sh"]
This diff is collapsed.
......@@ -35,5 +35,10 @@ format:
lint:
find code -name '*.cxx' -or -name '*.h*' | xargs clang-format --dry-run -Werror -ferror-limit=1
.PHONY: docs
docs:
mkdir -p public/doxygen
doxygen Doxyfile
clean:
rm -f obj/* bin/* lib/*
# Vancouver Waveform Analysis Toolkit
## Overview
A software suite for processing waveform data, designed to help particle physics researchers detect and analyze pulses.
## Usage
*Coming soon*
## Code Style
This project integrates with `clang-format` to ensure that the source code adheres to the [LLVM Coding Standards](https://llvm.org/docs/CodingStandards.html) for C++.
Install `clang-format` locally via Homebrew (MacOS) or your preferred package manager. Run `make lint` to detect any style errors, or just run `make format` before making a commit to let the tool automatically format your code. The CI pipeline running for every commit will reject code that does not pass the linting step, ensuring that all of the code merged to the `master` branch follows the standard style.
## Other Documentation
- [How our documentation works](docs/DOCUMENTATION.md)
# How our documentation works
# Overview
[Doxygen](https://www.doxygen.nl/manual) is used to generate our project documentation. It runs automatically via GitLab CI/CD for every commit made to the `master` branch, and the resulting documentation site is hosted using GitLab Pages.
The Doxygen configuration can be modified by changing the `Doxyfile` in the project root. Currently, it targets all `.cxx`, `.hxx`, `.h`, and `.md` files.
# Code Comments
Doxygen is configured to pick up JavaDoc-formatted comments, which look like this:
/**
* The first sentence is extracted as a brief description (include the period!).
* Anything after that is part of the more detailed class description.
*/
class Class:
// class body...
Refer to [this documentation](https://www.doxygen.nl/manual/docblocks.html#cppblock) for more information about the Doxygen syntax, which can be used to document everything from method parameters entire classes.
# Diagrams
Embed PlantUML directly into these Markdown documents using the following syntax:
\ startuml
!include ../docs/sample.puml
\ enduml
**NOTE:** do not include a space between the backslash and the `start/enduml` directives -- this is just done here to show the raw syntax.
Doxygen will render the files to image format and place them directly on the page. Check out this sample:
\startuml
!include ../docs/sample.puml
\enduml
**NOTE:** Doxygen exports documentation files to a directory called `public/` under the project root. In order to successfully embed UML diagrams from your `.puml` files, you need to pass the `!include` directive a relative path from `public/` to the target file (refer to the example above)
# Generating Documentation
As a rule, the `master` branch should be the source of truth for the project, but sometimes you may want to generate the documentation yourself. You can do this by running `make docs`, but you will need to ensure that the following dependencies are installed on your machine:
- [Doxygen](https://www.doxygen.nl/manual/install.html)
- [PlantUML](https://plantuml.com/faq-install)
- [Graphviz](https://graphviz.org/download/)
In order for Doxygen to find PlantUML on your system, set the environment variable `PLANTUML_JAR_PATH` to the absolute path of `plantuml.jar`.
Another option is to generate the documentation in a container by using the [`docgen`](../Dockerfile.docgen) container image included in this project:
docker run --rm -v '<path to vanwftk repo on host>:/vanwftk' registry.triumf.ca/phaar/vanwftk/docgen -c make docs
@startuml
interface Interface {
+method()
}
class Class {
+public_field
-private_field
+Class(int v1, int v2)
+method()
}
Class <|-- Interface
@enduml
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