to address following warning:
jenkins-build/build/workspace/ceph-pr-docs/doc/conf.py:102: RemovedInSphinx40Warning: The app.add_javascript() is deprecated. Please use app.add_js_file() instead.
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>
because it'd difficult to prepare (dummy) librados,libcephfs and librbd for
their python bindings in the building environment offered by Read the Docs.
Signed-off-by: Kefu Chai <kchai@redhat.com>
by default, the user agent's css sets `margin-block-end` of "ul ul" to
"0", which renders the unordered lists in release notes cluttered. as we
are using nested unordered list to present the changes in different
components.
in this change a customized css is added to reset the begin and end
margin of ul to 1em, which is the default value of top level ul.
Signed-off-by: Kefu Chai <kchai@redhat.com>
This reverts commit 88d6d499e0.
All doc builds are currently broken due to this change since
the HTML files are written without the necessary ".html"
extension.
Signed-off-by: Jason Dillaman <dillaman@redhat.com>
since sphinx 1.5, SOURCELINK_SUFFIX is always added to the source file,
and search page always tries to add it to the highlighted source result.
Signed-off-by: Kefu Chai <kchai@redhat.com>
Add '*.inc.rst' to the list of excluded patterns from sphinx-build. This
allows for using '*.inc.rst' as includes, and avoids duplicates. The
benefit of keeping the trailing '.rst' extension is that most IDEs use
that to render reStructured Text files.
Fixes: http://tracker.ceph.com/issues/37530
Signed-off-by: Ernesto Puerta <epuertat@redhat.com>
The license applicable to the files under doc/ was originally declared (in the
top-level file COPYING) to be "Creative Commons Attribution-ShareAlike (CC
BY-SA)" by ed0653b493
This license declaration omitted a version number.
Some time later ef7418421b was merged, mentioning
CC-BY-SA-1.0 as one of the Ceph source code licenses. Although the purpose of that
commit was only to summarize the canonical license information from COPYING, it
unintentionally became the only place in the source code where the doc license
version was specified.
In March 2018, the Debian project warned that CC-BY-SA-1.0 does not meet its
criteria for inclusion in the "free" section of the Debian distribution. (For
that, at least version 3.0 must be used.)
This new commit removes the doc license ambiguity by setting it to CC-BY-SA-3.0
in all places where the license is mentioned.
The exact spelling of the license name is taken from https://spdx.org/licenses/
Fixes: http://tracker.ceph.com/issues/23336
Signed-off-by: Nathan Cutler <ncutler@suse.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>
because it's deprecated, and is on by default in the specified sphinx
version (v1.6.3):
this change silences following warning:
build-doc/virtualenv/local/lib/python2.7/site-packages/sphinx/environment/__init__.py:683:
RemovedInSphinx17Warning: html_use_smartypants option is deprecated.
Smart quotes are on by default; if you want to disable or customize
them, use the smart_quotes option in docutils.conf.
RemovedInSphinx17Warning)
Signed-off-by: Kefu Chai <kchai@redhat.com>
so it can render the doxygen generated objects with the proper domain by
checking the extension of rendered source file.
Signed-off-by: Kefu Chai <kchai@redhat.com>
* move rst files from doc/man/8 into man/8
* extract man_pages setting for sphinx from doc/conf.py to man/conf.py
* generate all man pages in `make install`
* add python-sphinx to Build-Depends
* check for sphinx-build in `configure`
* run changed rst files through sphinx-build in `make check`
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>
The graph in quick-ceph-deploy.rst applies to
quick-start-preflight.rst.
The graph in deploy seems more complete, so I put the common
documentation in quick-common.rst and had it included.
doc/conf.py has 'start/quick-common.rst' in exclude patterns so that
sphinx does not complain about this file not being in toc.
Signed-off-by: Kevin Dalley <kevin@kelphead.org>
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>
Now you can create diagrams easily with the ".. ditaa::"
directive in the Sphinx documents.
admin/build-doc now checks for debs required for building
the documentation, or just lists commands missing for hosts
not using dpkg.
For more on Ditaa, see http://ditaa.sourceforge.net/
Signed-off-by: Tommi Virtanen <tommi.virtanen@dreamhost.com>
Most of the doc is user-oriented, let's isolate internals more.
Split into multiple files. Clean up RST.
Use Sphinx's graphviz plugin for graphs.
Signed-off-by: Tommi Virtanen <tommi.virtanen@dreamhost.com>
