Add comprehensive specification documentation (#30)

Co-authored-by: mikehagerty <[email protected]>

docs/Makefile

@@ -0,0 +1,21 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# 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)
+

docs/README.md

@@ -0,0 +1,61 @@
+# stationxml-doc
+StationXML Documentation
+
+## To generate the html/pdf documents
+
+    >make html
+
+and/or
+
+    >make latexpdf
+
+or running sphinx-build manually
+
+    >sphinx-build -b html . _build/html
+
+This will update the html files in _build/html
+
+## To update ReStructuredText documentation generated from the StationXML schema file
+
+    >python3 convert_xsd_to_rst.py ../fdsn-station.xsd .
+
+This will re-generate the following files from the XSD schema document:
+ - level-network.rst
+ - level-station.rst
+ - level-channel.rst
+ - level-response.rst
+
+## To modify the look and feel of the auto-generated level docs
+
+ The following css divs are described in:
+ _static/css/custom.css
+
+  - hatnote - describes the gray box of each element
+  - crumb - the navigation trails
+  - description - contains the element description
+  - type - contains the element type
+  - example - contains the element example
+
+Example rst
+
+       <BeginEffectiveTime>
+       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+       .. container:: hatnote hatnote-gray
+
+       .. container:: crumb
+
+          crumb:Network-->Comment-->BeginEffectiveTime
+
+       .. container:: type
+
+          type::blue:`dateTime`
+
+       .. container:: example
+
+          **Example**: <BeginEffectiveTime>2008-09-15T00:00:00</BeginEffectiveTime>
+
+Hint: If you change the css without changing any .rst files, you must first do:
+
+    >make clean   // deletes all the files in _build/
+
+before doing the sphinx-build or it won't take.

docs/_static/css/custom.css

@@ -0,0 +1,250 @@
+
+/* FDSN-style font baseline */
+body {
+  font-family: "Quattrocento Sans", Avenir, Helvetica, Arial, sans-serif;
+}
+
+/* Keep the logo from dominating the upper search pane */
+.logo {
+  max-height: 80px;
+}
+
+/* Set colors for search and navigation sidebar */
+.wy-side-nav-search,
+.wy-side-nav-search > a,
+.wy-side-nav-search > div.version,
+.wy-nav-top {
+  color: black;
+  background: white;
+}
+
+.wy-menu-vertical header,
+.wy-menu-vertical p.caption {
+  color: lightgray;
+  font-weight: bolder;
+}
+
+.wy-menu-vertical a,
+.wy-menu-vertical li.current > a {
+  color: white;
+}
+
+.wy-menu-vertical li.toctree-l2 a,
+.wy-menu-vertical li.toctree-l3 a,
+.wy-menu-vertical li.toctree-l4 a,
+.wy-menu-vertical li.toctree-l5 a,
+.wy-menu-vertical li.toctree-l6 a {
+  color: #404040;
+}
+
+.wy-nav-side {
+  color: black;
+  background: rgb(51,123,184); /* Darker blue */
+}
+
+.wy-menu-vertical li.toctree-l1.current > a,
+.wy-menu-vertical li.toctree-l1.current {
+  background: rgb(116,182,236); /* Medium blue */
+  border-bottom: rgb(116,182,236);
+  border-top: rgb(116,182,236);
+}
+
+.wy-menu-vertical li.toctree-l2.current > a,
+.wy-menu-vertical li.toctree-l2.current,
+.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a {
+  background: rgb(207,226,242); /* Light blue */
+}
+
+.wy-menu-vertical li.toctree-l2.current li.toctree-l3 a:hover {
+  background: #d6d6d6;
+}
+
+.wy-menu-vertical li.toctree-l2.current li.toctree-l3.current > a {
+  background: white;
+}
+
+/* Stuff ISTI set */
+h3, h4, h5, h6 {
+    display: block;
+    width: 100%;
+    background-color: #e8e8e8 ;
+    margin-bottom: 0 ;
+    margin-top: 0.9em ;
+    padding-left: 0.5em ;
+    padding-right: 0.5em ;
+    padding-top: 0.2em ;
+    padding-bottom: 0.2em ;
+}
+h2 {
+    display: block;
+    width: 100%;
+    /*background-color: #D6D6D6 ;*/
+    background-color: #e8e8e8 ;
+    margin-bottom: 0 ;
+    margin-top: 0.9em ;
+    padding-left: 0.5em ;
+    padding-right: 0.5em ;
+    padding-top: 0.2em ;
+    padding-bottom: 0.2em ;
+}
+h1 {
+    display: block;
+    width: 100%;
+    /*background-color: #2980b9 ;*/
+    background-color: #0088cc ;
+    margin-bottom: 0 ;
+    margin-top: 0.9em ;
+    padding-left: 0.5em ;
+    padding-right: 0.5em ;
+    padding-top: 0.2em ;
+    padding-bottom: 0.2em ;
+    color:white;
+}
+
+.MathJax_Display{
+}
+
+div.hatnote.hatnote-gray.docutils.container > div.description.docutils.container > blockquote > div > div > div {
+  font-size: 117% !important
+}
+
+.box
+{
+    border-color: #c8c8c8 ;
+    border-style: solid ;
+    border-width: 1px ;
+}
+
+.crumb {
+  height: 0;
+  position: relative;
+  left: 325px;
+  top: -25px;
+  color:#585858;
+}
+
+div.crumb > p {
+  font-size:small !important;
+}
+
+
+.breadcrumb
+{
+  font-color:white;
+  font-size:medium;
+}
+
+.hatnote_table
+{
+    border-color: #c8c8c8 ;
+    border-style: solid ;
+    border-width: 1px ;
+    margin-left: 0 ;
+    margin-right: 0 ;
+    padding-left: 0px;
+    padding-right: 0px ;
+    padding-bottom: 0px ;
+    padding-top: 0px ;
+    margin-bottom: 0px ;
+    margin-top: 0px ;
+}
+
+.hatnote
+{
+    border-color: #e8e8e8 ;
+    border-width: 1px ;
+    border-style: solid ;
+  /*
+    border-color: #c8c8c8 ;
+    */
+    font-size: x-small ;
+    /*font-style: italic ;*/
+    margin-left: auto ;
+    margin-right: auto ;
+    padding-left: 2em;
+    padding-right: 0px ;
+    padding-bottom: 0px ;
+    padding-top: 0px ;
+    margin-bottom: 0px ;
+    margin-top: 0px ;
+}
+.hatnote_table-gray { background-color: #e8e8e8 ; color: #000000 ; }
+.hatnote-gray { background-color: #e8e8e8 ; color: #000000 ; }
+.hatnote-yellow { background-color: #ffffe8 ; color: #000000 ; }
+.hatnote-red { background-color: #ffe8e8 ; color: #000000 ; }
+.hatnote-icon { height: 16px ; width: 16px ; }
+
+.rst-content .myownstyle .admonition-title {
+   background: #b99976
+}
+
+.rst-content .myownstyle {
+   background: #e5d3b3
+}
+
+.white {
+  color:white;
+  font-style:italic;
+  font-size: medium;
+}
+
+.red {
+  color:red;
+}
+.blue {
+  color:blue;
+}
+.italic {
+  font-style:italic;
+}
+
+.pink {
+  height: 200px;
+  width: 100%;
+  width: 500px;
+  background-color: pink;
+}
+
+table {
+  width:100%;
+}
+
+table.rows {
+  margin:0px;
+  padding:0px;
+  /*
+  width: 100%;
+  */
+  font-size: x-small ;
+}
+
+table.rows th {
+    background-color: #909090;
+    border-style: solid solid solid solid;
+    border-width: 0px 0px 0px 0px;
+    border-color: #AAAAAA;
+    /*text-align: center;*/
+    text-align: left;
+}
+table.rows td {
+    border-style: solid solid solid solid;
+    border-width: 0px 0px 0px 0px;
+    border-color: #AAAAAA;
+}
+
+table.rows tr {
+    border-style: solid solid solid solid;
+    border-width: 0px 0px 0px 0px;
+    border-color: #AAAAAA;
+}
+
+table.rows tr:nth-child(even) {
+    background-color: #F3F3FF;
+}
+table.rows tr:nth-child(odd) {
+    background-color: #FFFFEE;
+}
+
+table.head {
+    margin-bottom:0px;
+}

docs/_static/css/theme_overrides.css

@@ -0,0 +1,13 @@
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+   .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+   }
+
+   .wy-table-responsive {
+      overflow: auto !important;
+   }
+}