Revision dfa248269beadbdc7bb7f0ad35a876d7f0559490 authored by Corneliu Hoffman on 25 November 2022, 16:36:38 UTC, committed by Corneliu Hoffman on 07 December 2022, 09:15:26 UTC
1 parent eaec687
Makefile
# You can set these variables from the command line.
SPHINXOPTS = -j auto -aE -n -W --keep-going
SPHINXBUILD = poetry run sphinx-build
SOURCEDIR = .
TMPDOCDIR = /tmp/octezdoc
BUILDDIR = _build
TOPBUILDDIR = ../_build/default
DOCGENDIR = doc_gen
DOCERRORDIR = $(DOCGENDIR)/errors
P2PDOCEXE = $(TOPBUILDDIR)/docs/$(DOCGENDIR)/p2p_doc.exe
RPCDOCEXE = $(TOPBUILDDIR)/docs/$(DOCGENDIR)/rpc_doc.exe
ERRDOCEXE = $(TOPBUILDDIR)/docs/$(DOCERRORDIR)/error_doc.exe
NAMED_PROTOS = kathmandu lima
PROTOCOLS = $(NAMED_PROTOS) alpha
# The following variables names are lowercase, so their names can be computed
# from the names of the corresponding protocol directories
kathmandu_long = PtKathmankSpLLDALzWw7CGD2j2MtyveTwboEYokqUCP4a1LxMg
lima_long = PtLimaPtLMwfNinJi9rCfDPWea8dFgTZ1MeJ9f1m2SRic6ayiwW
alpha_long = ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK
kathmandu_short = PtKathma
lima_short = PtLimaPt
alpha_short = alpha
SCRIPTSDIR = scripts
CHECKXREFS = $(SCRIPTSDIR)/check_proto_xrefs.py
# Build all documentation (with CLI manuals and odoc) but without old PROTOCOLS
all: odoc-lite
# Html needs the API pages for OCaml modules, generated by odoc, because of
# the :package: custom roles in RST files; so run html *after* odoc
${MAKE} html
# Build the full documentation including archived protocols; for publishing only
full: odoc
# Same ordering constraint: html *after* odoc (see target "all")
${MAKE} html
# Build the manuals for a given protocol
%/octez-client.html:
@../octez-client -protocol $($(@D)_long) man -verbosity 3 -format html | sed "s#${HOME}#\$$HOME#g" > $@
%/octez-baker.html:
@../octez-baker-$($(@D)_short) man -verbosity 3 -format html | sed "s#${HOME}#\$$HOME#g" > $@
%/octez-accuser.html:
@../octez-accuser-$($(@D)_short) man -verbosity 3 -format html | sed "s#${HOME}#\$$HOME#g" > $@
manuals: \
$(PROTOCOLS:%=%/octez-client.html) \
$(PROTOCOLS:%=%/octez-baker.html) \
$(PROTOCOLS:%=%/octez-accuser.html)
# generic
@../octez-admin-client man -verbosity 3 -format html | sed "s#${HOME}#\$$HOME#g" > api/octez-admin-client.html
@../octez-signer man -verbosity 3 -format html | sed "s#${HOME}#\$$HOME#g" > api/octez-signer.html
@../octez-codec man -verbosity 3 -format html | sed "s#${HOME}#\$$HOME#g" > api/octez-codec.html
@../octez-snoop man -verbosity 3 -format html | sed "s#${HOME}#\$$HOME#g" > api/octez-snoop.html
# artificially depend on docexes to avoid concurrent dunes
.PHONY: odoc
odoc: docexes
cd $$(pwd)/.. ; dune build @doc
@rm -rf $$(pwd)/_build/api/odoc
@mkdir -p $$(pwd)/_build/api
@cp -r $$(pwd)/../_build/default/_doc $$(pwd)/_build/api/odoc
odoc-lite: docexes
rm -rf $(TMPDOCDIR)/
mkdir -p $(TMPDOCDIR)/
rsync --recursive --links --perms \
--include="src/proto_014*" --include="src/proto_015*" \
--exclude="src/proto_0*" \
../src ../tezt ../vendors ../dune ../dune-project $(TMPDOCDIR)/
# FIXME: https://gitlab.com/tezos/tezos/-/issues/2971
# The new version of odoc (2.1.0) is stricter than the old version (1.5.3),
# we temporarily deactivate the odoc checks.
# cd $(TMPDOCDIR); ODOC_WARN_ERROR=true dune build @doc
cd $(TMPDOCDIR); dune build @doc
@rm -rf _build/api/odoc
@mkdir -p _build/api
@cp -r $(TMPDOCDIR)/_build/default/_doc _build/api/odoc
.PHONY: linkcheck
linkcheck: html
@echo "Running linkcheck, outputs messages to $(BUILDDIR)/output.txt"
@$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) >$@;\
RESULT=$$?; cat $(BUILDDIR)/output.txt; exit $$RESULT
.PHONY: fixlinkcheck
fixlinkcheck:
@scripts/update_links.sh
.PHONY: redirectcheck
redirectcheck: html
@cd $$(pwd)/.. ; ./scripts/lint.sh --check-redirects
# xrefs should be checked:
# - on the active protocol using its numeric name (not the "active" symlink)
# - on each other protocol including alpha, also checking label defs (option -l)
xrefscheck:
$(CHECKXREFS) kathmandu
$(CHECKXREFS) -l lima
$(CHECKXREFS) -l alpha
scriptsindoccheck:
scripts/test_doc_scripts.sh install-bin-bionic
scripts/test_doc_scripts.sh install-bin-focal
scripts/test_doc_scripts.sh install-bin-fedora34
scripts/test_doc_scripts.sh install-bin-rc-bionic
scripts/test_doc_scripts.sh install-bin-rc-focal
scripts/test_doc_scripts.sh install-bin-rc-fedora34
scripts/test_doc_scripts.sh install-opam-scratch
scripts/test_doc_scripts.sh install-opam-bionic
scripts/test_doc_scripts.sh install-opam-focal
scripts/test_doc_scripts.sh compile-release-sources-buster
scripts/test_doc_scripts.sh compile-sources-buster
# build dune targets together to avoid concurrent dunes
docexes:
cd .. && dune build docs/$(DOCERRORDIR)/error_doc.exe docs/$(DOCGENDIR)/rpc_doc.exe docs/$(DOCGENDIR)/p2p_doc.exe
developer/metrics.csv:
../octez-node dump-metrics > developer/metrics.csv
$(ERRDOCEXE): docexes
$(RPCDOCEXE): docexes
$(P2PDOCEXE): docexes
api/errors.rst: $(ERRDOCEXE)
$(ERRDOCEXE) > api/errors.rst
%/rpc.rst: $(RPCDOCEXE)
$(RPCDOCEXE) index $(@D) > $@
user/default-acl.json: $(RPCDOCEXE)
$(RPCDOCEXE) acl > $@
rpc: user/default-acl.json shell/rpc.rst \
alpha/rpc.rst
# To be triggered manually when needed
rpc-protocols: $(NAMED_PROTOS:%=%/rpc.rst)
p2p: $(P2PDOCEXE) shell/p2p_usage.rst.inc
@$(P2PDOCEXE) < shell/p2p_usage.rst.inc > shell/p2p_api.rst
.PHONY: install-dependencies
install-dependencies:
@poetry install
user/node-config.json: user/node-config.sh
cd ..; ./docs/user/node-config.sh >docs/$@
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
html: api/errors.rst developer/metrics.csv user/node-config.json \
rpc p2p manuals install-dependencies
(echo ':orphan:'; echo ''; cat ../CHANGES.rst) > CHANGES-dev.rst
@$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
@ln -s active "$(BUILDDIR)/kathmandu" || true
# pylint does not support pyproject.toml configuration for now
# It is configured by ./.pylint.rc
# In pylint, we ignore the following additional errors:
# - C0330: pylint is wrong (https://github.com/psf/black/issues/48)
PYLINTRC?=../.pylintrc
PYLINT=PYLINTRC=${PYLINTRC} poetry run pylint --disable C0330
# pycodestyle does not support pyproject.toml configuration for now
# https://github.com/PyCQA/pydocstyle/issues/447
#
# In pycodestyle we ignore the following additional errors w.r.t to defaults
# (i.e. E121,E123,E126,E226,E24,E704,W503)
# - E203 :: pycodestyle is wrong (https://github.com/psf/black/issues/315)
# and black takes care of it
# - E231 :: same as E203
#
# Other error codes are detailed at https://www.flake8rules.com/
PYCODESTYLE=poetry run pycodestyle
PYCODESTYLE_OPTIONS=\
--ignore=E121,E123,E126,E226,E24,E704,W503,E203,E231 \
--max-line-length=80
PYTHON_SRCS?=conf.py _extensions/*.py scripts/*.py
pylint:
@echo "Linting with pylint, version:"
@poetry run pylint --version | sed 's/^/ /'
$(PYLINT) $(PYTHON_SRCS)
lint_black:
@echo "Running black formatter as style checker"
poetry run black --check $(PYTHON_SRCS)
pycodestyle:
@echo "Linting with pycodestyle version `poetry run pycodestyle --version` (`poetry run which pycodestyle`)"
$(PYCODESTYLE) $(PYCODESTYLE_OPTIONS) $(PYTHON_SRCS)
lint: pylint pycodestyle lint_black
clean:
@-rm -Rf "$(BUILDDIR)" linkcheck
@-rm -Rf api/errors.rst developer/metrics.csv user/node-config.json alpha/rpc.rst shell/rpc.rst shell/p2p_api.rst user/default-acl.json CHANGES-dev.rst
@-rm -Rf api/octez-*.html api/octez-*.txt active/octez-*.html kathmandu/octez-*.html lima/octez-*.html alpha/octez-*.html
![swh spinner](/static/img/swh-spinner.gif)
Computing file changes ...