General cleanup of top-level files

Add TODOs to AdminTools.rst and Utilities.rst

Author: jhendersonHDF

AdminTools.rst

@@ -5,6 +5,7 @@ Admin Tools
 The scripts described here are intended to be run on the server by "privileged" users.  These are all
 located in the ``util\admin`` directory.
 
+TODO: HSDS Admin scripts
 makepwd_file.py
 ---------------
 

Authorization.rst

@@ -4,15 +4,14 @@ Authorization and Authentication
 
 Request Authentication
 -----------------------
-h5serv supports HTTP Basic authentication to authenticate users by comparing an encrypted 
-username and password against a value stored within a password file.  
-(See :doc:`AdminTools` to create a password file and add user accounts.) 
+HDF Kita supports HTTP Basic authentication to authenticate users by comparing an encrypted 
+username and password against a value stored within a password file.
 
 If neither the requested object (Group, Dataset, or Committed Datatype) nor the object's root group
 has an Access Control List (ACL), authorization is not required and no authentication string
 needs to be supplied. See :doc:`../AclOps/index`) for information on how to use ACL's.
 
-If the requested object (or object's root group), does have an ACL, authorization may be required 
+If the requested object (or object's root group) does have an ACL, authorization may be required 
 (if the object is not publically readable),
 and if so the requestor will need to provide an Authorization header in the request.  If 
 authoriazation is required, but not provided, the server will return an HTTP Status of 401 - 
@@ -37,12 +36,11 @@ If the authorization string is validated, the server will verify the request is
 per the object's ACL list.  If not authorized a http status 403 - Forbidden will be returned.
 
 
-User ids and passwords
+User IDs and passwords
 ----------------------
 
-User ids and passwords are maintained in an HDF5 file referenced in the server config: 
-'password_file'.  The admin tool (See :doc:`AdminTools`) script: update_pwd.py can be used 
-to create new users and update passwords.
+User IDs and passwords are maintained in a plaintext file: 
+``admin/config/passwd.txt``.
+
 
 
- 

COPYING

@@ -1,6 +1,6 @@
 
 Copyright Notice and License Terms for 
-h5serv Software Service, Libraries and Utilities
+HDF Kita Software Service, Libraries and Utilities
 -----------------------------------------------------------------------------
 
 HDF Cloud Service, Libraries and Utilities

CommonErrorResponses.rst

@@ -2,19 +2,21 @@
 Common Error Responses
 ***************************
 
-For each request, h5serv returns a standard HTTP status code as described below.
-In general 2xx codes indicate success, 3xx codes some form of redirection, 4xx codes 
-client error, and 5xx codes for server errors.  In addition to the numeric code, h5serv
-will return an informational message as part of the response providing further 
-information on the nature of the error.
+For each request, HDF Kita returns a standard HTTP status code as described below.
+In general 2xx codes indicate success, 3xx codes are returned for some form of redirection,
+4xx codes are returned for a client error, and 5xx codes are returned for server errors. 
+In addition to the numeric code, HDF Kita will return an informational message as part of
+the response providing further information on the nature of the error.
 
  * ``200 OK`` - The request was completed successfully
- * ``201 Created`` - The request was fulfilled and a new resource (e.g. group, dataset, attribute was created) 
+ * ``201 Created`` - The request was fulfilled and a new resource (e.g. group, dataset, attribute was created)
  * ``400 Bad Request`` - The request was not structured correctly (e.g. a required key was missing).
- * ``401 Unauthorization`` - Use authentitcation is required, supply an Authentication header with valid user and password
+ * ``401 Unauthorization`` - User authentication is required, supply an Authentication header with a valid username and password
  * ``403 Forbidden`` - The requesting user does not have access to the requested resource
  * ``404 Not Found`` - The requested resource was not found (e.g. ``GET /groups/<id>`` where <id> was not a valid identifier for a group in the domain).
+ * ``405 Method Not Allowed`` - The HTTP request type was not valid for the given resource (e.g. ``PUT /datasets/<id>/type``)
  * ``409 Conflict`` - This error is used with PUT requests where the resources cannot be created because there is an existing resource with the same name (e.g. PUT / where the requested domain is already present).
  * ``410 Gone`` - The resource requested has been recently deleted.
+ * ``413 Selection Too Large`` - This error is used when the selection within a dataset encompasses too large of an area of data for the server to accept/return.
  * ``500 Internal Error`` - An unexpected error that indicates some problem occurred on the server.
  * ``501 Not Implemented`` - The request depends on a feature that is not yet implemented.

CommonRequestHeaders.rst

@@ -2,11 +2,11 @@
 Common Request Headers
 ***********************
 
-The following describe common HTTP request headers as used in h5serv:
+The following describe common HTTP request headers as used in HDF Kita:
 
- * Request line: The first line of the request, the format is of the form HTTP verb (GET, PUT, DELETE, or POST) followed by the path to the resource (e.g. /group/<uuid>.  Some operations take one or more query parameters (see relevant documentation) 
- * Accept: Specified the media type that is acceptable for the response.  Valid values are "application/json", and "*/*.  In addiiton, GET Value (see :doc:`DatasetOps/GET_Value`) supports the value "application/octet-stream"
+ * Request line: The first line of the request, the format is of the form HTTP verb (GET, PUT, DELETE, or POST) followed by the path to the resource (e.g. /group/<uuid>.  Some operations take one or more query parameters (see relevant documentation)
+ * Accept: Specifies the media type that is acceptable for the response.  Valid values are "application/json", and "*/*.  In addition, GET/PUT/POST Value (see :doc:`DatasetOps/GET_Value`, :doc:`DatasetOps/PUT_Value`, :doc:`DatasetOps/POST_Value`) support the value "application/octet-stream"
  * Authorization: A string that provides the requester's credentials for the request. See  :doc:`Authorization`
  * Host: the domain (i.e. related collection of groups, datasets, and attributes) that the request should apply to
- 
- Note: the host header can also be provided as a query paramter.  Example: https://data.hdfgroup.org:7258/?host=tall.test.data.hdfgroup.org 
+
+ Note: the host header can also be provided as a query parameter.  Example: https://data.hdfgroup.org:7258/?host=tall.test.data.hdfgroup.org

CommonResponseHeaders.rst

@@ -2,17 +2,17 @@
 Common Response Headers
 ***************************
 
-The following describes some of the common response lines returned by h5serv.
+The following describes some of the common response lines returned by HDF Kita.
 
- * Status Line: the first line of the ressponse will always by: "``HTTP/1.1``" followed by 
+ * Status Line: the first line of the response will always be: "``HTTP/1.1``" followed by 
     a status code (e.g. 200) followed by a reason message (e.g. "``OK``").  For errors, 
     an additional error message may be included on this line.
-    
+
  * Content-Length: the response size in bytes.
- 
+
  * Etag: a hash code that indicates the state of the requested resource.  If the client
     sees the same Etag value for the same request, it can assume the resource has not           
-    changes since the last request.
-    
- * Content-Type: the mime type of the response.  Currently always "``application/json``".
-    
+    changed since the last request.
+
+ * Content-Type: the mime type of the response.
+

Hypermedia.rst

@@ -2,13 +2,13 @@
 Hypermedia
 *************************
 
-h5serv supports the REST convention of **HATEOAS** or *Hypermedia as the Engine of 
-Application State*.  The idea is (see http://en.wikipedia.org/wiki/HATEOS for a full 
-explanation) is that each response include links to related resources related to 
+HDF Kita supports the REST convention of **HATEOAS** or *Hypermedia as the Engine of 
+Application State*.  The idea (see http://en.wikipedia.org/wiki/HATEOS for a full 
+explanation) is that each response includes links to resources related to 
 the requested resource.
 
 For example, consider the request for a dataset: ``GET /datasets/<id>``.  The response
-will be a JSON representation of the dataset describing it's type, shape, and other
+will be a JSON representation of the dataset describing its type, shape, and other
 aspects.  Related resources to the dataset would include:
 
  * the dataset's attributes
@@ -17,7 +17,7 @@ aspects.  Related resources to the dataset would include:
  * the root group of the domain the dataset is in
  * the domain resource
 
-So the ``GET /datasets/<id>`` response includes a key ``hrefs`` that contains an
+So the ``GET /datasets/<id>`` response includes a key ``hrefs`` that contains
 a JSON array.  Each array element has a key: ``href`` - the related resource, and a key:
 ``rel`` that denotes the type of relation.   Example:
 
@@ -33,12 +33,12 @@ a JSON array.  Each array element has a key: ``href`` - the related resource, an
       ] 
     }
     
-This enables clients to "explore" the api without detailed knowledge of the API.
+This enables clients to "explore" the API without detailed knowledge of it.
 
-This is the list of relations used in h5serv:
+This is the list of relations used in HDF Kita:
 
  * attributes - the attributes of the resource 
- * data - the resources data (used for datasets)
+ * data - the resource's data (used for datasets)
  * database - the collection of all datasets in the domain
  * groupbase - the collection of all groups in the domain
  * home - the domain the resource is a member of

Makefile

@@ -1,177 +1,25 @@
-# Makefile for Sphinx documentation
+# Minimal makefile for Sphinx documentation
 #
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
-PAPER         =
+SPHINXPROJ    = HDFKita
+SOURCEDIR     = .
 BUILDDIR      = _build
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
 $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
 endif
 
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
-
+# Put it first so that "make" without argument is like "make help".
 help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  pickle     to make pickle files"
-	@echo "  json       to make JSON files"
-	@echo "  htmlhelp   to make HTML files and a HTML help project"
-	@echo "  qthelp     to make HTML files and a qthelp project"
-	@echo "  devhelp    to make HTML files and a Devhelp project"
-	@echo "  epub       to make an epub"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-	@echo "  texinfo    to make Texinfo files"
-	@echo "  info       to make Texinfo files and run them through makeinfo"
-	@echo "  gettext    to make PO message catalogs"
-	@echo "  changes    to make an overview of all changed/added/deprecated items"
-	@echo "  xml        to make Docutils-native XML files"
-	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
-	@echo "  linkcheck  to check all external links for integrity"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
-
-clean:
-	rm -rf $(BUILDDIR)/*
-
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/h5serv.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/h5serv.qhc"
-
-devhelp:
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
-	@echo
-	@echo "Build finished."
-	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/h5serv"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/h5serv"
-	@echo "# devhelp"
-
-epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-	      "(use \`make latexpdf' here to do that automatically)."
-
-latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-latexpdfja:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through platex and dvipdfmx..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-texinfo:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo
-	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
-	@echo "Run \`make' in that directory to run these through makeinfo" \
-	      "(use \`make info' here to do that automatically)."
-
-info:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo "Running Texinfo files through makeinfo..."
-	make -C $(BUILDDIR)/texinfo info
-	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
-
-gettext:
-	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
-	@echo
-	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
-
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-xml:
-	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
-	@echo
-	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+.PHONY: help Makefile
 
-pseudoxml:
-	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
-	@echo
-	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

UsingIteration.rst

@@ -2,19 +2,19 @@
 Using Iteration
 ***************
 
-There are some operations that may return an arbitrary large list of results. For 
+There are some operations that may return an arbitrarily large list of results. For 
 example: ``GET /groups/<id>/attributes`` returns all the attributes of the 
 group object with the given id.  It's possible (if not common in practice) that the 
 group may contain hundreds or more attributes.
 
 If you desire to retrieve the list of attributes in batches (say you are developing a 
 user interface that has a "get next page" style button), you can use iteration.
 
-This is accomplished by adding query parameters to the request the limit the number of
+This is accomplished by adding query parameters to the request that limit the number of
 items returned and a marker parameter that identifies where the iteration should start 
 off.
 
-Let's flush out our example by supposing the group with UUID <id> has 1000 attributes 
+Let's flesh out our example by supposing the group with UUID <id> has 1000 attributes 
 named "a0000", "a0001", and so on.
 
 If we'd like to retrieve just the first 100 attributes, we can add a limit value to the 
@@ -31,7 +31,7 @@ marker value for the next request:
 
 This request will return attributes "a0100", "a0101", through "a0199".
 
-Repeat this pattern until less the limit items are returned.  This indicates that you've
+Repeat this pattern until less than 'Limit' items are returned.  This indicates that you've
 completed the iteration through all elements of the group.
 
 Iteration is also supported for links in a group, and the groups, datasets, and datatypes

Utilities.rst

@@ -2,9 +2,10 @@
 Utilities
 ###################
 
-The h5serv distribution includes the following utility scripts.  These are all
+The HDF Kita distribution includes the following utility scripts.  These are all
 located in the ``util`` directory.
 
+TODO: HSDS util scripts
 dumpobjdb.py
 ------------