Add docs with Sphinx documentation

# Minimal makefile for Sphinx documentation

#

# You can set these variables from the command line, and also

# from the environment for the first two.

SPHINXOPTS    ?=

SPHINXBUILD   ?= sphinx-build

SOURCEDIR     = source

BUILDDIR      = build

SPHINXMV      = sphinx-multiversion

# Put it first so that "make" without argument is like "make help".

help:

	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

versions:

	$(SPHINXMV) "$(SOURCEDIR)" "$(BUILDDIR)/html"

.PHONY: help 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

	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

@ECHO OFF

pushd %~dp0

REM Command file for Sphinx documentation

if "%SPHINXBUILD%" == "" (

	set SPHINXBUILD=sphinx-build

)

set SOURCEDIR=source

set BUILDDIR=build

if "%1" == "" goto help

%SPHINXBUILD% >NUL 2>NUL

if errorlevel 9009 (

	echo.

	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx

	echo.installed, then set the SPHINXBUILD environment variable to point

	echo.to the full path of the 'sphinx-build' executable. Alternatively you

	echo.may add the Sphinx directory to PATH.

	echo.

	echo.If you don't have Sphinx installed, grab it from

	echo.http://sphinx-doc.org/

	exit /b 1

)

%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

goto end

:help

%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

:end

popd

from pygments.lexer import ExtendedRegexLexer, RegexLexer, bygroups, words, \

    include, default, this, using, combined

from pygments.token import Text, Comment, Operator, Keyword, Name, String, \

    Number, Punctuation, Literal, Whitespace

from sphinx.highlighting import lexers

class RpccLexer(RegexLexer):

    """

    Lexer for rpcc definition files.

    """

    name = 'rpcc'

    aliases = ['rpcc']

    filenames = ['*.rpcc']

    tokens = {

        'root': [

            (r'[ \t]+', Text),

            (r'[,;{}\[\]()<>]', Punctuation),

            (r'#.*\n', Comment.Single),

            (words((

                'rpc', 'arguments', 'return_values'), prefix=r'\b', suffix=r'\b'),

             Keyword),

            include('builtins'),

            (words((

                'int8', 'int16', 'int32', 'int64',

                'uint8', 'uint16', 'uint32', 'uint64',

                'float', 'double', 'bool', 'string', 'exposed_buffer'), suffix=r'\b'),

             Keyword.Type),

            (r'(true|false)\b', Keyword.Constant),

            (r'(package)((?:\s|\\\s)+)', bygroups(Keyword.Namespace, Text), 'package'),

            (r'(rpc)(\s+)',

             bygroups(Keyword.Declaration, Text), 'rpc'),

            (r'\".*?\"', String),

            (r'\'.*?\'', String),

            (r'(\d+\.\d*|\.\d+|\d+)[eE][+-]?\d+[LlUu]*', Number.Float),

            (r'(\d+\.\d*|\.\d+|\d+[fF])[fF]?', Number.Float),

            (r'(\-?(inf|nan))\b', Number.Float),

            (r'0x[0-9a-fA-F]+[LlUu]*', Number.Hex),

            (r'0[0-7]+[LlUu]*', Number.Oct),

            (r'\d+[LlUu]*', Number.Integer),

            (r'[+-=:]', Operator),

            (r'([a-zA-Z_][\w.]*)([ \t]*)(=)',

             bygroups(Name.Attribute, Text, Operator)),

            (r'[a-zA-Z_][\w.]*', Name),

        ],

        'package': [

            (r'(?:[ \t]|\\\n)+', Text),

            (r'as\b', Keyword.Namespace),

            (r',', Operator),

            (r'[a-zA-Z_][\w.]*', Name.Namespace),

            default('#pop')  # all else: go back

        ],

        'rpc': [

            (r'[a-zA-Z_]\w*', Name.Class, '#pop'),

            default('#pop'),

        ],

        'builtins': [

            (words((

                'id', 'include_if'), prefix=r'(?<!\.)', suffix=r'\b'), Name.Function.Magic),

            (words((

                'compiler_defines', 'compiler_not_defines'), prefix=r'(?<!\.)', suffix=r'\b'), Name.Attribute)

        ]

    }

def setup(app):

    app.add_lexer('rpcc', RpccLexer)

{%- if current_version %}

<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">

  <span class="rst-current-version" data-toggle="rst-current-version">

    <span class="fa fa-book"> Other Versions</span>

    v: {{ current_version.name }}

    <span class="fa fa-caret-down"></span>

  </span>

  <div class="rst-other-versions">

    {%- if versions.tags %}

    <dl>

      <dt>Tags</dt>

      {%- for item in versions.tags %}

      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>

      {%- endfor %}

    </dl>

    {%- endif %}

    {%- if versions.branches %}

    <dl>

      <dt>Branches</dt>

      {%- for item in versions.branches %}

      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>

      {%- endfor %}

    </dl>

    {%- endif %}

  </div>

</div>

{%- endif %}

# Configuration file for the Sphinx documentation builder.

#

# This file only contains a selection of the most common options. For a full

# list see the documentation:

# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- 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

import pkg_resources

sys.path.insert(0, os.path.abspath('../..'))

sys.path.append(os.path.abspath("./_ext"))

# -- Project information -----------------------------------------------------

project = 'rpcc'

copyright = '2022, Barcelona Supercomputing Center'

author = 'Alberto Miranda'

# The full version, including alpha/beta/rc tags

release = pkg_resources.get_distribution("rpcc").version

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be

# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

# ones.

extensions = [

    'sphinx_rtd_theme',

    'sphinx.ext.autodoc',

    'sphinx.ext.autosectionlabel',

    'sphinx_copybutton',

    'sphinx_multiversion',

    'rpcc_lexer'

]

# Add any paths that contain templates here, relative to this directory.

templates_path = ['_templates']

# 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 = []

# -- 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'

# 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']