You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cassandra.apache.org by ru...@apache.org on 2017/12/04 21:49:26 UTC
cassandra git commit: Created docker configuration to build sphinx
docs.
Repository: cassandra
Updated Branches:
refs/heads/trunk 46f2397ab -> db81f6bff
Created docker configuration to build sphinx docs.
Patch by Joaquin Casares; Reviewed by Jon Haddad for CASSANDRA-13915.
This closes #154 (GH PR)
Project: http://git-wip-us.apache.org/repos/asf/cassandra/repo
Commit: http://git-wip-us.apache.org/repos/asf/cassandra/commit/db81f6bf
Tree: http://git-wip-us.apache.org/repos/asf/cassandra/tree/db81f6bf
Diff: http://git-wip-us.apache.org/repos/asf/cassandra/diff/db81f6bf
Branch: refs/heads/trunk
Commit: db81f6bffef1a8215fec28bb0522dc9684870627
Parents: 46f2397
Author: Jon Haddad <jo...@jonhaddad.com>
Authored: Mon Dec 4 13:48:51 2017 -0800
Committer: Jon Haddad <jo...@jonhaddad.com>
Committed: Mon Dec 4 13:49:10 2017 -0800
----------------------------------------------------------------------
build.xml | 1 +
doc/Dockerfile | 17 +++++++++++++++++
doc/README.md | 22 ++++++++++++++++++++++
doc/docker-compose.yml | 9 +++++++++
doc/source/cql/operators.rst | 2 --
doc/source/development/gettingstarted.rst | 8 ++++----
6 files changed, 53 insertions(+), 6 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cassandra/blob/db81f6bf/build.xml
----------------------------------------------------------------------
diff --git a/build.xml b/build.xml
index 1608fba..7c63c82 100644
--- a/build.xml
+++ b/build.xml
@@ -204,6 +204,7 @@
<target name="realclean" depends="clean" description="Remove the entire build directory and all downloaded artifacts">
<delete dir="${build.dir}" />
+ <delete dir="${doc.dir}/build" />
</target>
<!--
http://git-wip-us.apache.org/repos/asf/cassandra/blob/db81f6bf/doc/Dockerfile
----------------------------------------------------------------------
diff --git a/doc/Dockerfile b/doc/Dockerfile
new file mode 100644
index 0000000..074a9ed
--- /dev/null
+++ b/doc/Dockerfile
@@ -0,0 +1,17 @@
+# Dockerfile for building the Cassandra documentation.
+# If wanting to regenerate the documentation from scratch,
+# run `ant realclean` from the root directory of this project.
+
+FROM python:2.7
+
+WORKDIR /usr/src/code
+
+RUN pip install sphinx sphinx_rtd_theme
+
+RUN apt-get update \
+ && apt-get install -y \
+ ant \
+ default-jdk
+
+CMD ant gen-doc \
+ && echo "The locally built documentation can be found here:\n\n build/html/index.html\n\n"
http://git-wip-us.apache.org/repos/asf/cassandra/blob/db81f6bf/doc/README.md
----------------------------------------------------------------------
diff --git a/doc/README.md b/doc/README.md
index 9ba47a1..0badd8a 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -29,3 +29,25 @@ pip install sphinx sphinx_rtd_theme
The documentation can then be built from this directory by calling `make html`
(or `make.bat html` on windows). Alternatively, the top-level `ant gen-doc`
target can be used.
+
+To build the documentation with Docker Compose, run:
+
+```bash
+cd ./doc
+
+# build the Docker image
+docker-compose build build-docs
+
+# build the documentation
+docker-compose run build-docs
+```
+
+To regenerate the documentation from scratch, run:
+
+```bash
+# return to the root directory of the Cassandra project
+cd ..
+
+# remove all generated documentation files based on the source code
+ant realclean
+```
http://git-wip-us.apache.org/repos/asf/cassandra/blob/db81f6bf/doc/docker-compose.yml
----------------------------------------------------------------------
diff --git a/doc/docker-compose.yml b/doc/docker-compose.yml
new file mode 100644
index 0000000..27ac8d1
--- /dev/null
+++ b/doc/docker-compose.yml
@@ -0,0 +1,9 @@
+# docker-compose.yml for building the Cassandra documentation.
+
+version: '2.0'
+
+services:
+ build-docs:
+ build: .
+ volumes:
+ - ..:/usr/src/code
http://git-wip-us.apache.org/repos/asf/cassandra/blob/db81f6bf/doc/source/cql/operators.rst
----------------------------------------------------------------------
diff --git a/doc/source/cql/operators.rst b/doc/source/cql/operators.rst
index 45f52d9..1faf0d0 100644
--- a/doc/source/cql/operators.rst
+++ b/doc/source/cql/operators.rst
@@ -17,8 +17,6 @@
.. highlight:: cql
.. _arithmetic_operators:
-.. _number-arithmetic:
-.. _datetime--arithmetic:
Arithmetic Operators
--------------------
http://git-wip-us.apache.org/repos/asf/cassandra/blob/db81f6bf/doc/source/development/gettingstarted.rst
----------------------------------------------------------------------
diff --git a/doc/source/development/gettingstarted.rst b/doc/source/development/gettingstarted.rst
index b5005ab..c2f5ef3 100644
--- a/doc/source/development/gettingstarted.rst
+++ b/doc/source/development/gettingstarted.rst
@@ -36,23 +36,23 @@ Updating documentation
The Cassandra documentation is maintained in the Cassandra source repository along with the Cassandra code base. To submit changes to the documentation, follow the standard process for submitting a patch (:ref:`patches`).
Answering questions on the user list
-========================
+====================================
Subscribe to the user list, look out for some questions you know the answer to and reply with an answer. Simple as that!
See the `community <http://cassandra.apache.org/community/>`_ page for details on how to subscribe to the mailing list.
Reviewing and testing a submitted patch
-========================
+=======================================
Reviewing patches is not the sole domain of committers, if others have reviewed a patch it can reduce the load on the committers allowing them to write more great features or review more patches. Follow the instructions in :ref:`_development_how_to_review` or create a build with the patch and test it with your own workload. Add a comment to the JIRA ticket to let others know what you have done and the results of your work. (For example, "I tested this performance enhacement on our application's standard production load test and found a 3% improvement.")
Investigate and/or fix a reported bug
-========================
+=====================================
Often, the hardest work in fixing a bug is reproducing it. Even if you don't have the knowledge to produce a fix, figuring out a way to reliable reproduce an issues can be a massive contribution to getting a bug fixed. Document your method of reproduction in a JIRA comment or, better yet, produce an automated test that reproduces the issue and attach it to the ticket. If you go as far as producing a fix, follow the process for submitting a patch (:ref:`patches`).
Create unit tests and Dtests
-========================
+============================
Test coverage in Cassandra is improving but, as with most code bases, it could benefit from more automated test coverage. Before starting work in an area, consider reviewing and enhancing the existing test coverage. This will both improve your knowledge of the code before you start on an enhancement and reduce the chances of your change in introducing new issues. See :ref:`testing` and :ref:`patches` for more detail.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cassandra.apache.org
For additional commands, e-mail: commits-help@cassandra.apache.org