~loggerhead-team/loggerhead/trunk-rich : contents of docs/index.rst at revision 401.2.8

~loggerhead-team/loggerhead/trunk-rich : (revision 401.2.8)

401.2.7 by Tres Seaver Use 'Loggerhead' as the display name; fix typos.	1	Loggerhead: A web viewer for ``bzr`` branches
401.2.1 by Tres Seaver Add Sphinx-based documentation.	2	==============================================
	3
	4	Loggerhead is a web viewer for projects in bazaar. It can be used to navigate
	5	a branch history, annotate files, view patches, perform searches, etc.
401.2.7 by Tres Seaver Use 'Loggerhead' as the display name; fix typos.	6	Loggerhead is heavily based on `bazaar-webserve
401.2.4 by Tres Seaver Move cross-ref of bazaar-webserve and hgweb to intro graph; remove dead modindex and search.	7	<https://launchpad.net/bzr-webserve>`_, which was, in turn, loosely
	8	based on `hgweb <http://mercurial.selenic.com/wiki/HgWebDirStepByStep>`_.
	9
401.2.1 by Tres Seaver Add Sphinx-based documentation.	10
	11	Getting Started
	12	---------------
	13
401.2.2 by Tres Seaver ReST fixups, better cross-references.	14	Loggerhead depends on the following Python libraries.:
	15
	16	- SimpleTAL for templating.
	17
	18	- simplejson for producing JSON data.
	19
401.2.8 by Tres Seaver Consistent punctuation.	20	- Paste for the server. (You need version 1.2 or newer of Paste).
	21
	22	- Paste Deploy (optional, needed when proxying through Apache).
	23
	24	- flup (optional, needed to use FastCGI, SCGI or AJP).
401.2.2 by Tres Seaver ReST fixups, better cross-references.	25
	26
	27	Installing Dependencies Using Ubuntu Packages
	28	#############################################
	29
	30	.. code-block:: sh
	31
	32	$ sudo apt-get install python-simpletal
	33	$ sudo apt-get install python-simplejson
	34	$ sudo apt-get install python-paste
	35	$ sudo apt-get install python-pastedeploy
	36	$ sudo apt-get install python-flup
	37
	38	Installing Dependencies Using :command:`easy_install`
	39	#####################################################
	40
	41	.. code-block:: sh
	42
	43	$ easy_install \
	44	-f http://www.owlfish.com/software/simpleTAL/py2compatible/download.html \
	45	SimpleTAL
	46	$ easy_install simplejson
	47	$ easy_install Paste
	48	$ easy_install PasteDeploy
	49	$ easy_install flup
	50
	51
	52	Running the Standalone Loggerhead Server
	53	----------------------------------------
	54
	55	After installing all the dependencies, you should be able to run
	56	:command:`serve-branches` with the branch you want to serve on the
	57	command line:
401.2.1 by Tres Seaver Add Sphinx-based documentation.	58
	59	.. code-block:: sh
	60
	61	./serve-branches ~/path/to/branch
	62
401.2.2 by Tres Seaver ReST fixups, better cross-references.	63	By default, the script listens on port 8080, so head to
	64	http://localhost:8080/ in your browser to see the branch.
	65
	66	You can also pass a directory that contains branches to the script,
	67	and it will serve a very simple directory listing at other pages.
401.2.1 by Tres Seaver Add Sphinx-based documentation.	68
	69	You may update the Bazaar branches being viewed at any time.
	70	Loggerhead will notice and refresh, and Bazaar uses its own branch
	71	locking to prevent corruption.
	72
401.2.2 by Tres Seaver ReST fixups, better cross-references.	73	See :doc:`serve-branches` for all command line options.
	74
	75	Running Loggerhead as a Daemon
	76	------------------------------
	77
401.2.7 by Tres Seaver Use 'Loggerhead' as the display name; fix typos.	78	To run Loggerhead as a linux daemon:
401.2.1 by Tres Seaver Add Sphinx-based documentation.	79
401.2.2 by Tres Seaver ReST fixups, better cross-references.	80	1) Copy the ``loggerheadd`` scipt to ``/etc/init.d``
	81
	82	.. code-block:: sh
	83
	84	$ sudo cp ./loggerheadd /etc/init.d
401.2.1 by Tres Seaver Add Sphinx-based documentation.	85
401.2.7 by Tres Seaver Use 'Loggerhead' as the display name; fix typos.	86	2) Edit the file to configure where your Loggerhead is installed, and which
401.2.1 by Tres Seaver Add Sphinx-based documentation.	87	serve-branches options you would like.
401.2.1 by Tres Seaver Add Sphinx-based documentation.	88
401.2.2 by Tres Seaver ReST fixups, better cross-references.	89	.. code-block:: sh
	90
	91	$ sudo vim /etc/init.d/loggerheadd
	92
401.2.1 by Tres Seaver Add Sphinx-based documentation.	93	3) Register the service
401.2.2 by Tres Seaver ReST fixups, better cross-references.	94
	95	.. code-block:: sh
	96
401.2.7 by Tres Seaver Use 'Loggerhead' as the display name; fix typos.	97	# on upstart based systems like Ubuntu run:
401.2.2 by Tres Seaver ReST fixups, better cross-references.	98	$ sudo update-rc.d loggerheadd defaults
	99
401.2.7 by Tres Seaver Use 'Loggerhead' as the display name; fix typos.	100	# on Sysvinit based systems like Centos or SuSE run:
401.2.2 by Tres Seaver ReST fixups, better cross-references.	101	$ sudo chkconfig --add loggerheadd
	102
	103
	104	Using Loggerhead as a Bazaar Plugin
	105	------------------------------------
401.2.1 by Tres Seaver Add Sphinx-based documentation.	106
	107	This branch contains experimental support for using Loggerhead as a Bazaar
	108	plugin. To use it, place the top-level Loggerhead directory (the one
401.2.3 by Tres Seaver Explain plugin usage, link bazaar-webserve and hgweb.	109	containing this file) at ``~/.bazaar/plugins/loggerhead``. E.g.:
	110
	111	.. code-block:: sh
	112
	113	$ bzr branch lp:loggerhead ~/.bazaar/plugins/loggerhead
	114	$ cd ~/myproject
	115	$ bzr serve --http
401.2.1 by Tres Seaver Add Sphinx-based documentation.	116
	117
	118	Using a Config File
	119	-------------------
	120
	121	To hide branches from being displayed, add to ``~/.bazaar/locations.conf``,
	122	under the branch's section:
	123
	124	.. code-block:: ini
	125
	126	[/path/to/branch]
	127	http_serve = False
	128
	129	More configuration options to come soon.
	130
	131
401.2.6 by Tres Seaver Better section title.	132	Serving Loggerhead behind Apache
401.2.6 by Tres Seaver Better section title.	133	--------------------------------
401.2.1 by Tres Seaver Add Sphinx-based documentation.	134
	135	If you want to view Bazaar branches from your existing Apache
	136	installation, you'll need to configure Apache to proxy certain
	137	requests to Loggerhead. Adding lines like this to you Apache
	138	configuration is one way to do this:
	139
	140	.. code-block:: apache
	141
	142	<Location "/branches/">
	143	ProxyPass http://127.0.0.1:8080/branches/
	144	ProxyPassReverse http://127.0.0.1:8080/branches/
	145	</Location>
	146
	147	If Paste Deploy is installed, the :command:`serve-branches` script can be
	148	run behind a proxy at the root of a site, but if you're running it at
	149	some path into the site, you'll need to specify is using
	150	``--prefix=/some_path``.
	151
	152
	153	Search
	154	------
	155
	156	Search is currently supported by using the bzr-search plugin (available
401.2.2 by Tres Seaver ReST fixups, better cross-references.	157	at: https://launchpad.net/bzr-search ).
	158
401.2.1 by Tres Seaver Add Sphinx-based documentation.	159	You need to have the plugin installed and each branch indexed to allow
	160	searching on branches.
	161
401.2.5 by Tres Seaver Better section title.	162	Command-Line Reference
401.2.5 by Tres Seaver Better section title.	163	----------------------
401.2.2 by Tres Seaver ReST fixups, better cross-references.	164
	165	.. toctree::
	166	:maxdepth: 2
	167
	168	serve-branches
	169	start-loggerhead
	170	stop-loggerhead
	171
401.2.1 by Tres Seaver Add Sphinx-based documentation.	172
	173	Support
	174	-------
	175
401.2.3 by Tres Seaver Explain plugin usage, link bazaar-webserve and hgweb.	176	Discussion should take place on the bazaar-dev mailing list at
	177	mailto:bazaar@lists.canonical.com. You can join the list at
401.2.1 by Tres Seaver Add Sphinx-based documentation.	178	<https://lists.ubuntu.com/mailman/listinfo/bazaar>. You don't need to
	179	subscribe to post, but your first post will be held briefly for manual
	180	moderation.
	181
	182	Bugs are tracked on Launchpad; start at:
	183
	184	https://bugs.launchpad.net/loggerhead
	185
	186
	187	Hacking
	188	-------
	189
401.2.7 by Tres Seaver Use 'Loggerhead' as the display name; fix typos.	190	To run Loggerhead tests, you will need to install the package ``python-nose``,
	191	and run its :command:`nosetests` script in the Loggerhead directory:
401.2.1 by Tres Seaver Add Sphinx-based documentation.	192
	193	.. code-block:: sh
	194
	195	nosetests
	196
401.2.2 by Tres Seaver ReST fixups, better cross-references.	197
401.2.1 by Tres Seaver Add Sphinx-based documentation.	198	License
	199	-------
	200
	201	GNU GPLv2 or later.
	202
	203	See Also
	204	--------
	205
	206	https://launchpad.net/loggerhead
	207
401.2.4 by Tres Seaver Move cross-ref of bazaar-webserve and hgweb to intro graph; remove dead modindex and search.	208	Index
	209	=====
	210
	211	- :ref:`genindex`