funcparserlib is pulled in as a dependency by blockdiag. the latest version of
funcparserlib available on pypi is v0.3.6 which is not compatible with
Python3.8.
in this change, funcparserlib is installed from github instead to
address the build failure like:
File "/home/docs/checkouts/readthedocs.org/user_builds/ceph/envs/41855/lib/python3.8/site-packages/sphinxcontrib/seqdiag.py", line 26, in <module>
import seqdiag.utils.rst.nodes
File "/home/docs/checkouts/readthedocs.org/user_builds/ceph/envs/41855/lib/python3.8/site-packages/seqdiag/utils/rst/nodes.py", line 16, in <module>
from blockdiag.utils.rst import nodes
File "/home/docs/checkouts/readthedocs.org/user_builds/ceph/envs/41855/lib/python3.8/site-packages/blockdiag/utils/rst/nodes.py", line 21, in <module>
import blockdiag.builder
File "/home/docs/checkouts/readthedocs.org/user_builds/ceph/envs/41855/lib/python3.8/site-packages/blockdiag/builder.py", line 16, in <module>
from blockdiag import parser
File "/home/docs/checkouts/readthedocs.org/user_builds/ceph/envs/41855/lib/python3.8/site-packages/blockdiag/parser.py", line 43, in <module>
from funcparserlib.parser import (a, finished, forward_decl, many, maybe, skip,
File "/home/docs/checkouts/readthedocs.org/user_builds/ceph/envs/41855/lib/python3.8/site-packages/funcparserlib/parser.py", line 123
except NoParseError, e:
^
SyntaxError: invalid syntax
once https://github.com/vlasovskikh/funcparserlib/issues/65 is
addressed, we should drop this change.
Signed-off-by: Kefu Chai <tchaikov@gmail.com>
for rendering sequence-diagram. unlike ditaa, seqdiag allows us to
create sequence-diagram without worrying about the layout. and the
syntax is quite like that of dot.
Signed-off-by: Kefu Chai <kchai@redhat.com>
so we can build the command doc using ReadTheDoc infra, without adding
the generated rst file to the source repo.
before this change, all the commands are ordered alphabetically. after
this change, command docs are generated by two directives, and are
ordered separately. we could restructure the directives and merge them.
but let's leave it for a future change if this is important.
for more details on writing sphinx directives, see
https://www.sphinx-doc.org/en/master/extdev/markupapi.html and
https://docutils.sourceforge.io/docs/howto/rst-directives.html
Signed-off-by: Kefu Chai <kchai@redhat.com>
"luminous" is a magic number in these contexts, and we should use a
constant for representing it.
the "sphinx_substitution_extensions" sphinx extension is introduced for
performing the global subsitution.
Signed-off-by: Kefu Chai <kchai@redhat.com>
* use the latest stable sphinx
* unpin breathe, sphinx-autodoc-typehints, so pip can choose the
compatible versions without worrying about the compile failures.
Signed-off-by: Kefu Chai <kchai@redhat.com>
to address the build failure of
python -m pip install --exists-action=w --no-cache-dir -r admin/doc-requirements.txt
ERROR: ../src/python-common is not a valid editable requirement. It should either be a path to a local project or a VCS URL (beginning with svn+, git+, hg+, or bzr+).
Signed-off-by: Kefu Chai <kchai@redhat.com>
to silence following error:
ERROR: sphinx-autodoc-typehints 1.11.0 has requirement Sphinx>=3.0, but you'll have sphinx 2.4.3 which is incompatible.
* update breathe to the latest release, 4.14.2, which supports sphinx <
3.0
* pin sphinx to 2.4.4 the last sphinx before 3.0.0. as if sphinx >= 3.0
is used, we have errors like:
Invalid C declaration: Expected identifier in nested name, got keyword: int [error at 18]
CEPH_RADOS_API int rados_aio_append (rados_ioctx_t io, const char *oid, rados_completion_t completion, const char *buf, size_t len)
------------------^
Signed-off-by: Kefu Chai <kchai@redhat.com>
Don't use site-packages, since the host might have the same version, and
it won't have the ditaa and breathe.
Require Cython to make the venv sufficient.
Signed-off-by: Sage Weil <sage@redhat.com>
* use the latest Sphinx
* use the latest breathe. also, since there is no need to be compatible
with python2. we can move to 4.14.0 which is python3 only.
Signed-off-by: Kefu Chai <kchai@redhat.com>
to address https://github.com/sphinx-doc/sphinx/issues/3620, we need to
use sphinx with its fix at
e049f86b2d
in other words, we need to use sphinx v2.0.0 and up. but sphinx 2.0
requires python >= 3.5, so we have to use python3 for building the
documents.
in this change:
* doc-requirements.txt: install python3 packages on debian derivatives
* build-doc: install python3.6 packages from EPEL7, and use python3
venv for using sphinx2
* doc-requirements.txt: bump up all python packages to latest
stable.
Signed-off-by: Kefu Chai <kchai@redhat.com>
With `-e` the repository is cloned, leading to `git clean` skipping
the cloned dependencies due to the `.git` directory, and forcing manual
removal.
[nwatkins@daq ceph]$ git clean -dxf
Skipping repository build-doc/virtualenv/src/breathe
Skipping repository build-doc/virtualenv/src/sphinx-ditaa
Signed-off-by: Noah Watkins <nwatkins@redhat.com>
it works with setuptools and is now compatible with py3
the py3 branch is created to track the upstream's master branch
Signed-off-by: Kefu Chai <kchai@redhat.com>
* asphyxiate needs more toolings, see
https://github.com/ceph/asphyxiate/issues/1
* this commit basically reverts c96064
* use `autodoxygen` directive to doxygen referenced source files
* do not call `doxygen` explicitly in `build-doc`, `autodoxygen`
will take care of it.
Fixes: #6115Fixes: #6115
Signed-off-by: Kefu Chai <kchai@redhat.com>
TODO: path of librados.h is now just the basename
TODO: no enum support for now
TODO: no @bug support for now
Signed-off-by: Tommi Virtanen <tommi.virtanen@dreamhost.com>
The conditional before running pip install was unnecessary,
"pip install" on already installed packages is fast (as long
as it's not --upgrade), and --quiet makes it not spam the
console.
Signed-off-by: Tommi Virtanen <tommi.virtanen@dreamhost.com>
