also pin sphinx-autodoc-typehints to 1.18.3
to address following error:
ERROR: sphinx-autodoc-typehints 1.18.3 has requirement Sphinx>=4.5, but you'll have sphinx 4.4.0 which is incompatible.
Signed-off-by: Kefu Chai <tchaikov@gmail.com>
This PR changes the name "master" to "main" so
that builds (and, I assume, a great many other
things) will not fail.
Signed-off-by: Zac Dover <zac.dover@gmail.com>
bump sphinx to latest stable. to address following build failure
ERROR: sphinx-autodoc-typehints 1.17.0 has requirement Sphinx>=4, but you'll have sphinx 3.5.4 which is incompatible.
ERROR: sphinx-substitution-extensions 2022.2.16 has requirement sphinx>=4.0.0, but you'll have sphinx 3.5.4 which is incompatible.
also bump bump sphinx-rtd-theme, otherwise we'd have following
build failure:
ERROR: sphinx-rtd-theme 0.5.2 has requirement docutils<0.17, but you'll have docutils 0.17.1 which is incompatible.
Signed-off-by: Kefu Chai <tchaikov@gmail.com>
in breathe v4.33, it includes following commit
2498a43723
which specfies the app config value of "graphviz_dot". this annoys
sphinx:
WARNING: while setting up extension breathe: node class 'graphviz' is already registered, its visitors will be overridden
Traceback (most recent call last):
File "/home/docs/checkouts/readthedocs.org/user_builds/ceph/envs/44951/lib/python3.8/site-packages/sphinx/cmd/build.py", line 276, in build_main
app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
File "/home/docs/checkouts/readthedocs.org/user_builds/ceph/envs/44951/lib/python3.8/site-packages/sphinx/application.py", line 245, in __init__
self.setup_extension(extension)
File "/home/docs/checkouts/readthedocs.org/user_builds/ceph/envs/44951/lib/python3.8/site-packages/sphinx/application.py", line 402, in setup_extension
self.registry.load_extension(self, extname)
File "/home/docs/checkouts/readthedocs.org/user_builds/ceph/envs/44951/lib/python3.8/site-packages/sphinx/registry.py", line 430, in load_extension
metadata = setup(app)
File "/home/docs/checkouts/readthedocs.org/user_builds/ceph/envs/44951/lib/python3.8/site-packages/breathe/__init__.py", line 14, in setup
renderer_setup(app)
File "/home/docs/checkouts/readthedocs.org/user_builds/ceph/envs/44951/lib/python3.8/site-packages/breathe/renderer/sphinxrenderer.py", line 2613, in setup
app.add_config_value("graphviz_dot", "dot", "html")
File "/home/docs/checkouts/readthedocs.org/user_builds/ceph/envs/44951/lib/python3.8/site-packages/sphinx/application.py", line 535, in add_config_value
self.config.add(name, default, rebuild, types)
File "/home/docs/checkouts/readthedocs.org/user_builds/ceph/envs/44951/lib/python3.8/site-packages/sphinx/config.py", line 282, in add
raise ExtensionError(__('Config value %r already present') % name)
sphinx.errors.ExtensionError: Config value 'graphviz_dot' already present
Extension error:
Config value 'graphviz_dot' already present
this issue has been reported to upstream, see
https://github.com/michaeljones/breathe/issues/803
before it is fixed upstream, let's stick with 4.32.0
which is known to work.
Signed-off-by: Kefu Chai <tchaikov@gmail.com>
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 don't need to use virtualenv python package for creating a
virtualenv, the "venv" module in Python3 would suffice.
see also https://docs.python.org/3/library/venv.html
Signed-off-by: Kefu Chai <kchai@redhat.com>
otherwise livehtml uses the default html builder. so we can copy and
paste the partial URL to cross check the rendering result.
Signed-off-by: Kefu Chai <kchai@redhat.com>
Downside is you have to delete and re-run if the deps change. The venv
install is suuuuper slow for me, though, so this is a win.
Signed-off-by: Sage Weil <sage@newdream.net>
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>
per Radoslow Zarzynski, the build failure was due to missing Python.h
for the python version he was using on the system.
This reverts commit bc73204812.
Signed-off-by: Kefu Chai <kchai@redhat.com>
to silence the warning of
WARNING: --use-feature=2020-resolver no longer has any effect, since it is now the default dependency resolver in pip. This will become an error in pip 21.0.
Signed-off-by: Kefu Chai <kchai@redhat.com>
since all the python bindings are required for building the doc, extract
them into admin/doc-pybind.txt.
because the pybind python extensions require Cython python module to build,
we have to move them into another requirement file, and install them after
Cython is installed.
Signed-off-by: Kefu Chai <kchai@redhat.com>
it is time-consuming to rebuild the python bindings every time we
rebuild the document, it'd be ideal if we could just build document.
in this change, in addition to "html" and "doc", "livehtml" argument is
now supported by build-doc script, so one can just use
./build-doc livehtml
to build and start a web server. whenever a change in doc/ is detected,
the document is rebuilt. for more details, see
https://pypi.org/project/sphinx-autobuild/
Signed-off-by: Kefu Chai <kchai@redhat.com>
since we are able to build the python bindings using the stub
implementation of C binding, let's enable the API docs build.
Signed-off-by: Kefu Chai <kchai@redhat.com>
to silence the warning like
follow the suggestion from pip
ERROR: After October 2020 you may experience errors when installing or updating packages. This is because pip will change the way that it resolves dependency conflicts.
We recommend you use --use-feature=2020-resolver to test your packages with the new resolver before it becomes the default.
Fixes: https://tracker.ceph.com/issues/47636
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>
RTD does not support installing system packages, the only ways to install
dependencies are setuptools and pip. while ditaa is a tool written in
Java. so we need to find a native python tool allowing us to render ditaa
images. plantweb is able to the web service for rendering the ditaa
diagram. so let's use it as a fallback if "ditaa" is not around.
also start a new line after the directive, otherwise planweb server will
return 500 at seeing the diagram.
Signed-off-by: Kefu Chai <kchai@redhat.com>
as compilers targeting ELF does not add the leading "_" to symbol names,
while clang on OSX always do this.
and remove the underscore from the symbol name when generating the
function name, as the compiler will add it back for us.
Signed-off-by: Kefu Chai <kchai@redhat.com>
