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>
which is not supported by ld on OSX.
also, pass the rpath argument as a new command line argument instead
using -rpath=foo, which is not supported by llvm linker.
Signed-off-by: Kefu Chai <kchai@redhat.com>
we should not `set -e` at the very beginning of this script, which fails
the script if any dependency is missing without printing out error
messages.
in this change `set -e` is removed. and refactor the code to print the
error message.
Signed-off-by: Kefu Chai <kchai@redhat.com>
since we've dropped the support of python36-*, i.e. python packages
provided by EPEL7 before RHEL7/CentOS7 included python3. as before the
inclusion of python3 as supported python3, python packages are named
python36-*. and they don't provide python3-*. so we had to install
python36-* explicitly. now that we are able to use the python3-*
packages, we can just install python3-*.
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>
