Initial commit

.gitignore

@@ -0,0 +1 @@
+_build/

.travis.yml

@@ -0,0 +1,13 @@
+sudo: false
+language: python
+dist: xenial
+matrix:
+  include:
+    - python: '3.7'
+install:
+  - pip install -r requirements.txt
+  - pip install "ltd-conveyor>=0.4.2,<0.5"
+script:
+  - sphinx-build -b html -a -n -d _build/doctree . _build/html
+after_success:
+  - ltd upload --travis --dir _build/html --product ittn-018

COPYRIGHT

@@ -0,0 +1 @@
+Copyright 2020 Association of Universities for Research in Astronomy, Inc. (AURA)

Makefile

@@ -0,0 +1,58 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    = -n
+SPHINXBUILD   = sphinx-build
+PAPER         =
+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. Try 'running pip install -r requirements.txt' to get the necessary Python dependencies.)
+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 epub changes linkcheck refresh-bib
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html         to make standalone HTML files"
+	@echo "  epub         to make an epub"
+	@echo "  linkcheck    to check all external links for integrity"
+	@echo "  refresh-bib  to update LSST bibliographies in lsstbib/"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+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."
+
+refresh-bib:
+	refresh-lsst-bib -d lsstbib
+	@echo
+	@echo "Commit the new bibliographies: git add lsstbib && git commit -m \"Update bibliographies.\""

README.rst

@@ -0,0 +1,78 @@
+.. image:: https://img.shields.io/badge/ittn--018-lsst.io-brightgreen.svg
+   :target: https://ittn-018.lsst.io
+.. image:: https://travis-ci.com/lsst-it/ittn-018.svg
+   :target: https://travis-ci.com/lsst-it/ittn-018
+..
+  Uncomment this section and modify the DOI strings to include a Zenodo DOI badge in the README
+  .. image:: https://zenodo.org/badge/doi/10.5281/zenodo.#####.svg
+     :target: http://dx.doi.org/10.5281/zenodo.#####
+
+##############################################
+Network Infrastructure High-Level Design (HLD)
+##############################################
+
+ITTN-018
+========
+
+Network Infrastructure High-Level Design (HLD) ITTN
+
+**Links:**
+
+- Publication URL: https://ittn-018.lsst.io
+- Alternative editions: https://ittn-018.lsst.io/v
+- GitHub repository: https://github.com/lsst-it/ittn-018
+- Build system: https://travis-ci.com/lsst-it/ittn-018
+
+
+Build this technical note
+=========================
+
+You can clone this repository and build the technote locally with `Sphinx`_:
+
+.. code-block:: bash
+
+   git clone https://github.com/lsst-it/ittn-018
+   cd ittn-018
+   pip install -r requirements.txt
+   make html
+
+.. note::
+
+   In a Conda_ environment, ``pip install -r requirements.txt`` doesn't work as expected.
+   Instead, ``pip`` install the packages listed in ``requirements.txt`` individually.
+
+The built technote is located at ``_build/html/index.html``.
+
+Editing this technical note
+===========================
+
+You can edit the ``index.rst`` file, which is a reStructuredText document.
+The `DM reStructuredText Style Guide`_ is a good resource for how we write reStructuredText.
+
+Remember that images and other types of assets should be stored in the ``_static/`` directory of this repository.
+See ``_static/README.rst`` for more information.
+
+The published technote at https://ittn-018.lsst.io will be automatically rebuilt whenever you push your changes to the ``master`` branch on `GitHub <https://github.com/lsst-it/ittn-018>`_.
+
+Updating metadata
+=================
+
+This technote's metadata is maintained in ``metadata.yaml``.
+In this metadata you can edit the technote's title, authors, publication date, etc..
+``metadata.yaml`` is self-documenting with inline comments.
+
+Using the bibliographies
+========================
+
+The bibliography files in ``lsstbib/`` are copies from `lsst-texmf`_.
+You can update them to the current `lsst-texmf`_ versions with::
+
+   make refresh-bib
+
+Add new bibliography items to the ``local.bib`` file in the root directory (and later add them to `lsst-texmf`_).
+
+.. _Sphinx: http://sphinx-doc.org
+.. _DM reStructuredText Style Guide: https://developer.lsst.io/restructuredtext/style.html
+.. _this repo: ./index.rst
+.. _Conda: http://conda.pydata.org/docs/
+.. _lsst-texmf: https://lsst-texmf.lsst.io

_static/README

@@ -0,0 +1,8 @@
+To add images, add the image file (png, svg or jpeg preferred) to this
+_static/ directory. The reST syntax for adding the image is
+
+.. figure:: /_static/filename.ext
+    :name: fig-label
+    :target: http://target.link/url
+
+    Caption text.

conf.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python
+#
+# Sphinx configuration file
+# see metadata.yaml in this repo to update document-specific metadata
+
+import os
+from documenteer.sphinxconfig.technoteconf import configure_technote
+
+# Ingest settings from metadata.yaml and use documenteer's configure_technote()
+# to build a Sphinx configuration that is injected into this script's global
+# namespace.
+metadata_path = os.path.join(os.path.dirname(__file__), 'metadata.yaml')
+with open(metadata_path, 'r') as f:
+    confs = configure_technote(f)
+g = globals()
+g.update(confs)
+
+# Add intersphinx inventories as needed
+# http://www.sphinx-doc.org/en/stable/ext/intersphinx.html
+# Example:
+#
+#     intersphinx_mapping['python'] = ('https://docs.python.org/3', None)

index.rst

@@ -0,0 +1,61 @@
+..
+  Technote content.
+
+  See https://developer.lsst.io/restructuredtext/style.html
+  for a guide to reStructuredText writing.
+
+  Do not put the title, authors or other metadata in this document;
+  those are automatically added.
+
+  Use the following syntax for sections:
+
+  Sections
+  ========
+
+  and
+
+  Subsections
+  -----------
+
+  and
+
+  Subsubsections
+  ^^^^^^^^^^^^^^
+
+  To add images, add the image file (png, svg or jpeg preferred) to the
+  _static/ directory. The reST syntax for adding the image is
+
+  .. figure:: /_static/filename.ext
+     :name: fig-label
+
+     Caption text.
+
+   Run: ``make html`` and ``open _build/html/index.html`` to preview your work.
+   See the README at https://github.com/lsst-sqre/lsst-technote-bootstrap or
+   this repo's README for more info.
+
+   Feel free to delete this instructional comment.
+
+:tocdepth: 1
+
+.. Please do not modify tocdepth; will be fixed when a new Sphinx theme is shipped.
+
+.. sectnum::
+
+.. TODO: Delete the note below before merging new content to the master branch.
+
+.. note::
+
+   **This technote is not yet published.**
+
+   Network Infrastructure High-Level Design (HLD) ITTN
+
+.. Add content here.
+.. Do not include the document title (it's automatically added from metadata.yaml).
+
+.. .. rubric:: References
+
+.. Make in-text citations with: :cite:`bibkey`.
+
+.. .. bibliography:: local.bib lsstbib/books.bib lsstbib/lsst.bib lsstbib/lsst-dm.bib lsstbib/refs.bib lsstbib/refs_ads.bib
+..    :style: lsst_aa

lsstbib/README.md

@@ -0,0 +1,14 @@
+# lsstbib
+
+This directory contains local copies of LSST's common LaTeX bibliographies from [lsst-texmf](https://github.com/lsst/lsst-texmf/tree/master/texmf/bibtex/bib).
+The recommended way to update these files is with (from the root technote directory):
+
+```
+make refresh-bib
+git add lsstbib
+git commit -m "Update lsst bibliographies"
+```
+
+Add new bibliography items specifically for this technote to the `local.bib` file in the root directory of this technote.
+Later, you should add these bibliography items to `lsst-texmf` and remove them from `local.bib` so that other documents can use the reference.
+See the [lsst-texmf docs for instructions](https://lsst-texmf.lsst.io/developer.html#updating-bibliographies).