You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by ja...@apache.org on 2012/12/06 12:34:40 UTC
[3/50] [abbrv] git commit: Add Sphinx-related build changes into
READMEs
Add Sphinx-related build changes into READMEs
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/db621d23
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/db621d23
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/db621d23
Branch: refs/heads/1536-feature-add-docs
Commit: db621d23c8325d0c6b401209fda3c4f8cb084f0e
Parents: 956a57e
Author: Noah Slater <ns...@apache.org>
Authored: Mon Dec 3 10:04:54 2012 +0100
Committer: Jan Lehnardt <ja...@apache.org>
Committed: Thu Dec 6 12:31:32 2012 +0100
----------------------------------------------------------------------
AUTHORS | 1 -
BUGS | 6 ++-
DEVELOPERS | 114 ++++++++++++++++++++++++++++++++++++++++++-------
INSTALL.Unix | 51 ++++++++++++++++------
INSTALL.Windows | 36 ++++++++++-----
LICENSE | 115 ++++++++++++++++++++++++++++++++++++++++++++++----
NOTICE | 28 ++++++------
README | 4 ++
8 files changed, 287 insertions(+), 68 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/db621d23/AUTHORS
----------------------------------------------------------------------
diff --git a/AUTHORS b/AUTHORS
index e55c0b0..49b5ef1 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -21,5 +21,4 @@ documentation or developing software. Some of these people are:
* Dave Cottlehuber <dc...@apache.org>
* Jason Smith <jh...@apache.org>
-
For a list of other credits see the `THANKS` file.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/db621d23/BUGS
----------------------------------------------------------------------
diff --git a/BUGS b/BUGS
index 8cd1d16..1bdc478 100644
--- a/BUGS
+++ b/BUGS
@@ -1,6 +1,8 @@
Apache CouchDB BUGS
===================
-Please see the [documentation][1] on how to report bugs with Apache CouchDB.
+Visit our issue tracker:
-[1] http://couchdb.apache.org/community/issues.html
+ https://issues.apache.org/jira/browse/CouchDB
+
+You can use this to report bugs, request features, or suggest enhancements.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/db621d23/DEVELOPERS
----------------------------------------------------------------------
diff --git a/DEVELOPERS b/DEVELOPERS
index 84976d7..f61b77b 100644
--- a/DEVELOPERS
+++ b/DEVELOPERS
@@ -10,30 +10,95 @@ Dependencies
You will need the following installed:
- * GNU Automake (>=1.6.3) (http://www.gnu.org/software/automake/)
- * GNU Autoconf (>=2.59) (http://www.gnu.org/software/autoconf/)
* GNU Libtool (http://www.gnu.org/software/libtool/)
+ * GNU Automake (>=1.6.3) (http://www.gnu.org/software/automake/)
+ * GNU Autoconf (>=2.68) (http://www.gnu.org/software/autoconf/)
+ * GNU Autoconf Archive (http://www.gnu.org/software/autoconf-archive/)
+ * pkg-config (http://www.freedesktop.org/wiki/Software/pkg-config)
+
+You may also need:
+
+ * Sphinx (http://sphinx.pocoo.org/)
+ * LaTex (http://www.latex-project.org/)
+ * GNU Texinfo (http://www.gnu.org/software/texinfo/)
* GNU help2man (http://www.gnu.org/software/help2man/)
-The `help2man` tool is optional, but will generate `man` pages for you.
+These optional dependencies are required for building the documentation.
+
+You will need these optional dependencies installed if:
+
+ * You are preparing a distribution archive
+
+However, you do not need them if:
+
+ * You are building from a distribution archive, or
+ * You don't care about building the documentation
Debian-based (inc. Ubuntu) Systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-You can install the dependencies by running:
+You can install the required dependencies by running:
+
+ sudo apt-get install libtool
+ sudo apt-get install automake
+ sudo apt-get install autoconf
+ sudo apt-get install autoconf-archive
+ sudo apt-get install pkg-config
- apt-get install automake autoconf libtool help2man
+Optional dependencies:
+
+ sudo apt-get install help2man
+ sudo apt-get install python-sphinx
+ sudo apt-get install texlive-latex-base
+ sudo apt-get install texlive-latex-recommended
+ sudo apt-get install texlive-latex-extra
+ sudo apt-get install texlive-fonts-recommended
+ sudo apt-get install texinfo
Be sure to update the version numbers to match your system's available packages.
Mac OS X
~~~~~~~~
-You can install the dependencies by running:
+Install Homebrew, if you do not have it already:
+
+ https://github.com/mxcl/homebrew
+
+You can install the required dependencies by running:
+
+ brew install libtool
+ brew install automake
+ brew install autoconf
+ brew install autoconf-archive
+ brew install pkg-config
+
+Unless you want to install the optional dependencies, skip to the next section.
- port install automake autoconf libtool help2man
+Install what else we can with Homebrew:
-You will need MacPorts installed to use the `port` command.
+ brew install help2man
+
+If you don't already have pip installed, install it:
+
+ sudo easy_install pip
+
+Now, install the required Python packages:
+
+ sudo pip install sphinx
+ sudo pip install docutils
+ sudo pip install pygments
+
+Download MaxTeX from here:
+
+ http://www.tug.org/mactex/
+
+Follow the instructions to get a working LaTeX install on your system.
+
+Windows
+~~~~~~~
+
+ Follow the instructions in INSTALL.Windows and build all components
+ from source, using the same Visual C++ compiler and runtime.
Bootstrapping
-------------
@@ -44,6 +109,29 @@ Bootstrap the pristine source by running:
You must repeat this step every time you update your source checkout.
+Configuring
+-----------
+
+Configure the source by running:
+
+ ./configure
+
+Note that this will not fail when the optional dependencies are missing.
+
+To ensure the optional dependencies are installed, run:
+
+ ./configure --enable-strictness
+
+If you don't care about docs and want to skip the whole thing, run:
+
+ ./configure --disable-docs
+
+If you're working on the build system itself, you can run:
+
+ ./configure --disable-tests
+
+This skips the tests allowing quicker `make' cycles.
+
Testing
-------
@@ -60,17 +148,13 @@ Please report any problems to the developer's mailing list.
Releasing
---------
-The release procedure is documented in the project wiki:
+The release procedure is documented here:
https://wiki.apache.org/couchdb/Release_procedure
Unix-like Systems
~~~~~~~~~~~~~~~~~
-Configure the source by running:
-
- ./configure
-
Prepare the release artefacts by running:
make distcheck
@@ -84,10 +168,6 @@ The release artefacts can be found in the root source directory.
Microsoft Windows
~~~~~~~~~~~~~~~~~
-Configure the source by running:
-
- ./configure
-
Prepare the release artefacts by running:
make dist
http://git-wip-us.apache.org/repos/asf/couchdb/blob/db621d23/INSTALL.Unix
----------------------------------------------------------------------
diff --git a/INSTALL.Unix b/INSTALL.Unix
index bd8c9d0..0cb60e8 100644
--- a/INSTALL.Unix
+++ b/INSTALL.Unix
@@ -3,6 +3,16 @@ Apache CouchDB README.Unix
A high-level guide to Unix-like systems, inc. Mac OS X and Ubuntu.
+Community installation guides are available on the wiki:
+
+ http://wiki.apache.org/couchdb/Installation
+
+This document is the canonical source of installation information. However, many
+systems have gotchas that you need to be aware of. In addition, dependencies
+frequently change as distributions update their archives. If you're running into
+trouble, be sure to check out the wiki. If you have any tips to share, please
+also update the wiki so that others can benefit from your experience.
+
Troubleshooting
---------------
@@ -33,32 +43,42 @@ You should have the following installed:
* GNU Compiler Collection (http://gcc.gnu.org/)
* libcurl (http://curl.haxx.se/libcurl/)
* help2man (http://www.gnu.org/s/help2man/)
+ * Python (>= 2.7) for docs (http://python.org/)
+ * Python Sphinx (>=1.1.3) (http://pypi.python.org/pypi/Sphinx)
It is recommended that you install Erlang OTP R13B-4 or above where possible.
You will only need libcurl if you plan to run the JavaScript test suite. And
help2man is only need if you plan on installing the CouchDB man pages.
-
-Ubuntu
-~~~~~~
-
-For up to date instructions, please see:
-
- http://wiki.apache.org/couchdb/Installing_on_Ubuntu
-
-Unfortunately, it seems that installing dependancies on Ubuntu is troublesome.
+Python and Sphinx are only required for building the online documentation.
Debian-based Systems
~~~~~~~~~~~~~~~~~~~~
-You can install the build tools by running:
+You can install the dependencies by running:
sudo apt-get install build-essential
+ sudo apt-get install erlang-base-hipe
+ sudo apt-get install erlang-dev
+ sudo apt-get install erlang-manpages
+ sudo apt-get install erlang-eunit
+ sudo apt-get install erlang-nox
+ sudo apt-get install libicu-dev
+ sudo apt-get install libmozjs-dev
+ sudo apt-get install libcurl4-openssl-dev
+
+There are lots of Erlang packages. If there is a problem with your install, try
+a different mix. There is more information on the wiki. Additionally, you might
+want to install some of the optional Erlang tools which may also be useful.
-You can install the other dependencies by running:
+Be sure to update the version numbers to match your system's available packages.
+
+For up to date instructions, please see:
- sudo apt-get install erlang libicu-dev libmozjs-dev libcurl4-openssl-dev
+ http://wiki.apache.org/couchdb/Installing_on_Debian
-Be sure to update the version numbers to match your system's available packages.
+ http://wiki.apache.org/couchdb/Installing_on_Ubuntu
+
+Unfortunately, it seems that installing dependencies on Ubuntu is troublesome.
Mac OS X
~~~~~~~~
@@ -69,7 +89,10 @@ You can install the build tools by running:
You can install the other dependencies by running:
- brew install erlang icu4c spidermonkey curl
+ brew install erlang
+ brew install icu4c
+ brew install spidermonkey
+ brew install curl
You may want to link ICU so that CouchDB can find the header files automatically:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/db621d23/INSTALL.Windows
----------------------------------------------------------------------
diff --git a/INSTALL.Windows b/INSTALL.Windows
index b75b80a..89ab231 100644
--- a/INSTALL.Windows
+++ b/INSTALL.Windows
@@ -14,6 +14,10 @@ There is a wiki for general documentation:
http://wiki.apache.org/couchdb/
+And some Windows-specific tips:
+
+ http://wiki.apache.org/couchdb/Quirks_on_Windows
+
There are collection of friendly mailing lists:
http://couchdb.apache.org/community/lists.html
@@ -25,28 +29,36 @@ Dependencies
You will need the following installed:
- * Erlang OTP (=14B01) (http://erlang.org/)
- * ICU (=4.4.*) (http://icu.sourceforge.net/)
- * OpenSSL (http://www.openssl.org/)
- * Mozilla SpiderMonkey (1.7) (http://www.mozilla.org/js/spidermonkey/)
- * libcurl (http://curl.haxx.se/libcurl/)
- * Cygwin (http://www.cygwin.com/)
- * Visual Studio 2008 (http://msdn.microsoft.com/en-gb/vstudio/default.aspx)
+ * Erlang OTP (>=14B01) (http://erlang.org/)
+ * ICU (>=4.*) (http://icu.sourceforge.net/)
+ * OpenSSL (>=0.9.8r) (http://www.openssl.org/)
+ * Mozilla SpiderMonkey (=1.8.5) (http://www.mozilla.org/js/spidermonkey/)
+ * libcurl (http://curl.haxx.se/libcurl/)
+ * Cygwin (http://www.cygwin.com/)
+ * Microsoft SDK 7.0 or 7.1 (http://www.microsoft.com/en-us/download/details.aspx?id=8279)
+ * Python (>= 2.7) for docs (http://python.org/)
+ * Python Sphinx (>=1.1.3) (http://pypi.python.org/pypi/Sphinx)
General Notes
-------------
+ * When installing Cygwin, be sure to select all the `development` tools.
+
* When installing Erlang, you must build it from source.
- The CouchDB build requires a number of the Erlang build scripts.
+ * The CouchDB build requires a number of the Erlang build scripts.
- * When installing ICU, select the binaries built with Visual Studio 2008.
+ * All dependent libraries should be built with the same version of
+ microsoft SDK.
- * When installing Cygwin, be sure to select all the `development` tools.
+ * Do not try to link against libraries built with, or included in,
+ Cygwin or MingW. They are not compatible with the Erlang/OTP or CouchDB
+ build scripts.
- * When installing libcurl, be sure to install by hand.
+ * ICU version 4.6 and later will build cleanly using MSBuild.
- The Cygwin binaries are incompatible and will not work with Erlang.
+ * Python and Sphinx are only required for building the online documentation.
+ Use cygwin-provided Python and install Sphinx via easy_install or pip.
Setting Up Cygwin
-----------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/db621d23/LICENSE
----------------------------------------------------------------------
diff --git a/LICENSE b/LICENSE
index be511b1..be2404d 100644
--- a/LICENSE
+++ b/LICENSE
@@ -201,20 +201,120 @@
See the License for the specific language governing permissions and
limitations under the License.
-
Apache CouchDB Subcomponents
The Apache CouchDB project includes a number of subcomponents with separate
copyright notices and license terms. Your use of the code for the these
subcomponents is subject to the terms and conditions of the following licenses.
-For the m4/ac_check_icu.m4 component:
+For the share/doc/build/html/_static components:
+
+ Copyright (c) 2007-2011 by the Sphinx team (see AUTHORS file).
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are
+ met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+For the share/doc/build/html/_static/jquery.js component:
+
+ Copyright 2010, John Resig
+
+ Copyright 2010, The Dojo Foundation
+
+ Copyright 2012 jQuery Foundation and other contributors
+ http://jquery.com/
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For the share/doc/build/html/_static/underscore.js component:
+
+ Copyright (c) 2009-2012 Jeremy Ashkenas, DocumentCloud
- Copyright (c) 2005 Akos Maroy <da...@tyrell.hu>
+ Permission is hereby granted, free of charge, to any person
+ obtaining a copy of this software and associated documentation
+ files (the "Software"), to deal in the Software without
+ restriction, including without limitation the rights to use,
+ copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following
+ conditions:
+
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ OTHER DEALINGS IN THE SOFTWARE.
+
+For the share/doc/static/rtd.css components:
+
+ Copyright (c) 2007-2011 by the Sphinx team (see AUTHORS file).
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are
+ met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
- Copying and distribution of this file, with or without modification, are
- permitted in any medium without royalty provided the copyright notice
- and this notice are preserved.
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
For the share/www/script/jquery.js component:
@@ -239,8 +339,7 @@ For the share/www/script/jquery.js component:
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-For the share/www/script/jquery-ui-1.8.11.custom.min.js and
- share/www/style/jquery-ui-1.8.11.custom.css components:
+For the share/www/script/jquery-ui-* components:
Copyright (c) 2011 Paul Bakaus, http://jqueryui.com/
http://git-wip-us.apache.org/repos/asf/couchdb/blob/db621d23/NOTICE
----------------------------------------------------------------------
diff --git a/NOTICE b/NOTICE
index ef3ff9e..e627b92 100644
--- a/NOTICE
+++ b/NOTICE
@@ -6,18 +6,6 @@ The Apache Software Foundation (http://www.apache.org/).
This product also includes the following third-party components:
- * ac_check_icu.m4 (http://autoconf-archive.cryp.to/ac_check_icu.html)
-
- Copyright 2008, Akos Maroy <da...@tyrell.hu>
-
- * ac_check_curl.m4 (http://autoconf-archive.cryp.to/ac_check_curl.html)
-
- Copyright 2008, Akos Maroy <da...@tyrell.hu>
-
- * pkg.m4 (http://http://pkg-config.freedesktop.org/wiki/)
-
- Copyright 2004, Scott James Remnant <sc...@netsplit.com>
-
* jQuery (http://jquery.com/)
Copyright 2011, John Resig
@@ -28,7 +16,7 @@ This product also includes the following third-party components:
* json2.js (http://www.json.org/)
- In the public domain
+ Public domain
* MochiWeb (http://code.google.com/p/mochiweb/)
@@ -64,7 +52,7 @@ This product also includes the following third-party components:
* snappy (http://code.google.com/p/snappy/)
- Copyright 2005 and onwards Google Inc.
+ Copyright 2005, Google Inc.
* snappy-erlang-nif (https://github.com/fdmanana/snappy-erlang-nif)
@@ -73,3 +61,15 @@ This product also includes the following third-party components:
* CoffeeScript (http://coffeescript.org/)
Copyright 2011, Jeremy Ashkenas
+
+ * Sphinx (http://sphinx-doc.org/)
+
+ Copyright 2011, the Sphinx team
+
+ * Sizzle (http://sizzlejs.com/)
+
+ Copyright 2010, The Dojo Foundation
+
+ * Underscore.js 1.4.2 (http://underscorejs.org)
+
+ Copyright 2012, Jeremy Ashkenas
http://git-wip-us.apache.org/repos/asf/couchdb/blob/db621d23/README
----------------------------------------------------------------------
diff --git a/README b/README
index 0d125fb..33b854d 100644
--- a/README
+++ b/README
@@ -34,6 +34,10 @@ If you're getting a cryptic error message, see:
For general help, see:
http://couchdb.apache.org/#mailing-list
+
+We also have an IRC channel:
+
+ http://webchat.freenode.net/?channels=couchdb
The mailing lists provide a wealth of support and knowledge for you to tap into.
Feel free to drop by with your questions or discussion. See the official CouchDB