Metacat

Also add in the OAI-PMH documentation contributed by Duane Costa.

The Metacat Administrator's Guide has now been completely ported to Sphinx/ReST format, and I've written new chapters for several of the new features, including DataONE and OAI-PMH (from Duane Costa). I've also included the Javadoc API directly in the Admin Guide now. Your revisions would be appreciated.

I also updated the Metacat build so that the documentation can be built automatically when building Metacat (assuming that you have Sphinx installed on your local build machine). Running:

ant documentation war

will produce a war file with the documentation (including both Sphinx docs and Javadoc) shipping inside the knb.war file, so any given metacat deployment that is built this way will have the docs available at:

http://<somehost.org>/knb/docs

I also modified the Hudson build on dev-testing so that the docs would build automatically with each change in Metacat, and so a common place to be able to find the current documentation build is via Hudson, here:

http://dev-testing.dataone.org:8080/hudson/job/Metacat/javadoc/

I changed the hudson build configuration fairly significantly to get it all to run (path problems under hudson), so let me know if the knb.war produced by hudson has any problems. I'm sure there is more editing to be done on the admin guide, especially updated screenshots in a variety of places, but I think we're now in a pretty good place to maintain it well. Your comments in particular on the draft DataONE chapter would be great.

Edits to metacat/trunk/docs/user/metacat/metacat/source/intro.rst

The edited version is attached. Matt said to provide a diff of my changes.
Only changes are the chapters have different numbers and the API is a link now, not an appendix.

diff b intro.rst intro_mgb.rst
72c72
< Chapter Two contains instructions for downloading and installing Metacat and the
--

Chapter Four contains instructions for downloading and installing Metacat and the

74,75c74,75
< Chapter Three covers how to configure Metacat, both for new and upgraded
< installations. Chapter Four details the ways in which you can customize the
---

Chapter Five covers how to configure Metacat, both for new and upgraded
installations. Chapter Seven details the ways in which you can customize the

78,79c78,79
< and creating your own desktop client (like Morpho). Chapter Five discusses how
< to work with Metacat's embedded Geoserver. Chapter Six describes how to set up the
---

and creating your own desktop client (like Morpho). Chapter Eight discusses how
to work with Metacat's embedded Geoserver. Chapter Nine describes how to set up the

81c81
< each other, effectively backing up metadata and data files. Chapter Seven looks
---

each other, effectively backing up metadata and data files. Chapter Ten looks

84c84
< to Metacat. Chapter Eight discusses logging, Chapter Nine contains instructions
---

to Metacat. Chapter Twelve discusses logging, Chapter Thirteen contains instructions

86,87c86,88
< Web searches. Metacat's Java API is included as an appendix at the end of the
< guide.
---

Web searches. Metacat's Java API is `available`_ for developers.

.. _API documentation: ./api/index.html

diff u intro.rst intro_mgb.rst
-- intro.rst 2012-06-05 13:15:16.000000000 0700
++ intro_mgb.rst 2012-06-05 16:04:48.000000000 -0700
@ -69,22 +69,23 @
-------------------
This Administrator's guide includes information for installing, configuring,
managing and extending Metacat for both Linux, Mac OS, and Windows systems.
-Chapter Two contains instructions for downloading and installing Metacat and the
+Chapter Four contains instructions for downloading and installing Metacat and the
applications required to run the software on Linux and Microsoft platforms.
-Chapter Three covers how to configure Metacat, both for new and upgraded
-installations. Chapter Four details the ways in which you can customize the
+Chapter Five covers how to configure Metacat, both for new and upgraded
+installations. Chapter Seven details the ways in which you can customize the
Metacat interface so users can access and submit information easily: using
Metacat's generic web-interface (the Registry), creating your own HTML forms,
-and creating your own desktop client (like Morpho). Chapter Five discusses how
-to work with Metacat's embedded Geoserver. Chapter Six describes how to set up the
+and creating your own desktop client (like Morpho). Chapter Eight discusses how
+to work with Metacat's embedded Geoserver. Chapter Nine describes how to set up the
Metacat's replication service, which permits Metacat servers to share data with
-each other, effectively backing up metadata and data files. Chapter Seven looks
+each other, effectively backing up metadata and data files. Chapter Ten looks
at the Metacat Harvester, a program that automates the retrieval of EML
documents from one or more sites and their subsequent upload (insert or update)
-to Metacat. Chapter Eight discusses logging, Chapter Nine contains instructions
+to Metacat. Chapter Twelve discusses logging, Chapter Thirteen contains instructions
for creating a site map, which makes individual metadata entries available via
-Web searches. Metacat's Java API is included as an appendix at the end of the
-guide.
+Web searches. Metacat's Java API is `available`_ for developers.

+.. _API documentation: ./api/index.html

Metacat Features
 ----------------

Section 4. Downloading and Installing
Just a presentation issue.
NOT IMPORTANT.
In Firefox, Safari, and chrome, http://dev-testing.dataone.org:8080/hudson/job/Metacat-unstable/javadoc/install.html
displays with the light-grey background div.side-bar overlapping the text of the main part of the page when that text is in a

.  

This section is hands-down the best ever instructions Ive seen for such complex installation.

Minor edits to configuration page: two same-page links and one word change.

Applied Gastil's edits to intro.rst and configuration.rst

one important edit is the description of the "delete" behavior.

The other edits are just references to Figures and an updated pathQuery example.

I have not finished revising this section 7 but wanted to be sure the "delete" edit gets in.

thank you.

Gastil, are there any more modifications you want to get into the user docs? Thanks!

Spoke with Gastil -- we're good for this round of edits.

Original Bugzilla ID was 5516