Commit 58c3e6ce authored by Dimitris Lampridis's avatar Dimitris Lampridis Committed by Dimitris Lampridis

doc: preparation for release documentation

parent 1394f372
# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: doc/conf.py
# Build documentation with MkDocs
#mkdocs:
# configuration: mkdocs.yml
# Optionally build your docs in additional formats such as PDF and ePub
formats:
- pdf
# Optionally set the version of Python and requirements required to build your docs
python:
version: 3.7
install:
- requirements: doc/requirements.txt
# Exclude all submodules, they are not needed for documentation
submodules:
exclude: all
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
## [1.0.0] - 2019-xx-yy
### Added
- First release of WRTD.
[Unreleased]: https://www.ohwr.org/project/wrtd/compare/libwrtd-v1.0.0...master
[1.0.0]: https://www.ohwr.org/project/wrtd/tags/libwrtd-v1.0.0
The project is based on the Mock Turtle infrastructure. On top of the
Mock Turtle we have the White Rabbit Trigger Distribution.
The project is made of:
- two real-time applications running on the Mock Turtle CPUs
- one library which provide the application's abstraction to communicate with
the real-time applications.
- a set of command line tools for the White Rabbit Trigger Distribution
configuration
RULES
=====
The master branch is protected so you need special permission to touch it.
Do you development on your own branch and push it.
In the project we are following the Linux kernel code style.
All the functions, defines, structures, enumeraters exported should use
the `wrtd_` prefix.
This diff is collapsed.
......@@ -4,4 +4,4 @@ The aim of the project is to provide a system that is able to receive triggers
from some external source and distribute these triggers to remote nodes over
the White Rabbit network.
For more information, check out the project [Wiki](https://ohwr-gitlab.cern.ch/project/wrtd/wikis/Home).
For more information, check out the project [Wiki](https://ohwr.org/project/wrtd/wikis/Home) and the available [Documentation](https://wrtd.readthedocs.io).
doxygen-output/
doxygen-wrtd-output/
*.log
_build
build_env
.doxystamp
......@@ -12,37 +12,22 @@ BUILDDIR = _build
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile doxygen doxygen-clean
.PHONY: help doxygen Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
$(MAKE) doxygen TARGET=$@
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
GIT_VERSION = $(shell cd $(src); git describe --dirty --long --tags)
DOXY_OUT ?= doxygen-output
# Build the documentation with or without the internals details
ifdef SHOW_INTERNALS
EXCLUDE_FILES = ""
BRIEF = "API Documentation - With Internals"
else
EXCLUDE_FILES = "../lib/libwrtd-internal.h"
BRIEF = "API Documentation"
endif
GIT_VERSION = $(shell git describe --always --dirty --long --tags)
doxygen:
ifeq ($(TARGET),clean)
@echo "Remove Doxygen files"
@rm -rf $(DOXY_OUT) $(BUILDDIR)
@rm -rf _build doxygen-wrtd-output .doxystamp
else
GIT_VERSION=$(GIT_VERSION) EXCLUDE_FILES=$(EXCLUDE_FILES) BRIEF=$(BRIEF) \
OUTPUT=$(DOXY_OUT) doxygen ./doxygen-wrtd-config
$(MAKE) .doxystamp
endif
# List of Doxygen folders to consider
......
......@@ -37,7 +37,6 @@ extensions = [
'sphinx.ext.graphviz',
'sphinx.ext.coverage',
'breathe',
'recommonmark',
]
......@@ -151,7 +150,7 @@ html_theme = 'sphinx_rtd_theme'
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#
# html_logo = None
#html_logo = 'graphics/CERN-logo_outline-small.jpg'
# The name of an image file (relative to this directory) to use as a favicon of
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
......@@ -275,7 +274,7 @@ latex_documents = [
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#
# latex_logo = None
#latex_logo = 'graphics/CERN-logo_outline-small.jpg'
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
......@@ -346,12 +345,19 @@ texinfo_documents = [
#
# texinfo_no_detailmenu = False
from recommonmark.transform import AutoStructify
breathe_projects = {
"wrtd": "doxygen-wrtd-output/xml/",
}
breathe_default_project = "wrtd"
# This is necessary to run doxygen on ReadTheDocs
import subprocess, os
read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
if read_the_docs_build:
subprocess.call('make doxygen', shell=True)
def setup(app):
app.add_config_value('recommonmark_config', {
'enable_math': True,
'enable_inline_math': True,
'enable_eval_rst': True
}, True)
app.add_transform(AutoStructify)
numfig = True
PROJECT_NAME = "White Rabbit Trigger Distribution"
PROJECT_NUMBER = $(GIT_VERSION)
PROJECT_BRIEF = $(BRIEF)
PROJECT_BRIEF = "WRTD"
PROJECT_LOGO =
OUTPUT_DIRECTORY = $(OUTPUT)
OUTPUT_DIRECTORY = doxygen-wrtd-output
CREATE_SUBDIRS = YES
TAB_SIZE = 8
OPTIMIZE_OUTPUT_FOR_C = YES
......@@ -11,10 +11,12 @@ EXTRACT_STATIC = YES
CASE_SENSE_NAMES = YES
WARN_NO_PARAMDOC = YES
WARN_IF_UNDOCUMENTED = NO
INPUT = ../lib ../include/wrtd-common.h
INPUT = $(DOXINPUT)
RECURSIVE = YES
EXCLUDE = $(EXCLUDE_FILES)
EXCLUDE = $(DOXEXCL)
GENERATE_HTML = YES
GENERATE_LATEX = YES
GENERATE_LATEX = NO
GENERATE_XML = YES
This source diff could not be displayed because it is too large. You can view the blob instead.
This diff is collapsed.
This diff is collapsed.
This source diff could not be displayed because it is too large. You can view the blob instead.
<mxfile modified="2019-05-15T16:43:47.051Z" host="www.draw.io" agent="Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0" etag="Xg36wqg7Vy9voEuI-ICU" version="10.6.7" type="device"><diagram id="9yaM3EnqbtjqUlc5I0cC" name="Page-1">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</diagram></mxfile>
\ No newline at end of file
......@@ -3,14 +3,18 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
===============================================
White Rabbit Trigger Distribution documentation
===============================================
.. toctree::
:maxdepth: 2
:maxdepth: 4
:caption: Contents
introduction
wrtd_api
.. todolist::
Indices and tables
------------------
......
------------
Introduction
------------
White Rabbit Trigger Distribution (WRTD) is a generic framework for distributing triggers (Events)
over a White Rabbit network.
.. figure:: graphics/wrtd_overview.png
:name: wrtd-overview
:align: center
:alt: alternate text
:figclass: align-center
figure are like images but with a caption
As can be seen in :numref:`wrtd-overview`
Installation
============
.. todo::
Decide on installation and document it
Major WRTD Elements
===================
Internally, WRTD consists of the following elements:
- An HDL module for FPGAs, built on top of `Mock Turtle <https://ohwr.org/project/mock-turtle>`_
(MT) and the `White Rabbit PTP Core <https://ohwr.org/project/wr-cores/wikis/Wrpc-core>`_. When
instantiated in an FPGA, this module handles the generation/reception of triggers, while
providing the user with MT cores to run their own application(s) (eg. to control an ADC).
- An embedded library framework for (MT) firmware development. This library can be used when
developing firmware for the MT cores, in order to connect user applications with the
generation/reception of triggers.
- A host library framework that provides a way for configuring the WRTD nodes and scheduling the
generation/reception of triggers.
However, for most use cases, only the last element (the host library) will be of importance to the
user, since a device will come pre-programmed with the necessary gateware and firmware.
Section :ref:`host_lib` provides all the details on how to use the host library.
.. _host_lib:
-----------------
WRTD Host Library
-----------------
WRTD Timestamps
===============
.. doxygenstruct:: wrtd_tstamp
:members:
WRTD Error Codes
================
.. doxygenenum:: wrtd_status
WRTD Attributes
===============
.. doxygenenum:: wrtd_attr
.. doxygendefine:: WRTD_GLOBAL_REP_CAP_ID
WRTD API
========
Initialisation
--------------
.. doxygenfunction:: wrtd_init
.. doxygenfunction:: wrtd_close
.. doxygenfunction:: wrtd_reset
Attribute Handling
------------------
.. doxygenfunction:: wrtd_set_attr_bool
.. doxygenfunction:: wrtd_get_attr_bool
.. doxygenfunction:: wrtd_set_attr_int32
.. doxygenfunction:: wrtd_get_attr_int32
.. doxygenfunction:: wrtd_set_attr_string
.. doxygenfunction:: wrtd_get_attr_string
.. doxygenfunction:: wrtd_set_attr_tstamp
.. doxygenfunction:: wrtd_get_attr_tstamp
Error Handling
--------------
.. doxygenfunction:: wrtd_get_error
.. doxygenfunction:: wrtd_error_message
Event Log
---------
.. doxygendefine:: WRTD_LOG_ENTRY_SIZE
.. doxygenfunction:: wrtd_clear_event_log_entries
.. doxygenfunction:: wrtd_get_next_event_log_entry
Alarms
------
.. doxygenfunction:: wrtd_add_alarm
.. doxygenfunction:: wrtd_disable_all_alarms
.. doxygenfunction:: wrtd_remove_alarm
.. doxygenfunction:: wrtd_remove_all_alarms
.. doxygenfunction:: wrtd_get_alarm_name
Rules
-----
.. doxygenfunction:: wrtd_add_rule
.. doxygenfunction:: wrtd_disable_all_rules
.. doxygenfunction:: wrtd_remove_rule
.. doxygenfunction:: wrtd_remove_all_rules
.. doxygenfunction:: wrtd_get_rule_name
.. doxygenfunction:: wrtd_reset_rule_stats
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