Notes about publishing a site generated by Sphinx

Sphinx is a popular documentation generation tool. (It was originally created for publishing Python documentation.)

Marion Le Bras developed these notes (note: link only works inside the NIST network) for how to get Sphinx docs published on NIST Pages.

The summary of what's required are:

1. Include a .nojekyll file in the root of your nist-pages branch. Sphinx does the page generation so Jekyll is not needed. There is a Sphinx extension to do this for you: sphinx.ext.githubpages
2. You can use the nature template but not the RTD template, which overwrites the layout.html file.
3. Make sure your Sphinx conf.py points to the _templates/ directory (it does by default). templates_path = ["_templates"]
4. (Not a Sphinx issue but a NIST Pages issue): note that the leaveNotice and nist-header-footer repos specify different versions of jQuery in their documentation. In general the latest jQuery 1.x should work but we don't test every version. I have not run across any incompatibilities with any 1.x versions thus far. Try the latest version and if you have problems let us know.

Sample Sphinx layout.html

{% block extrahead %}
<link rel="stylesheet" href="https://pages.nist.gov/nist-header-footer/css/nist-combined.css">
  <script src="https://code.jquery.com/jquery-1.12.4.min.js" type="text/javascript"></script>
  <script src="https://pages.nist.gov/nist-header-footer/js/nist-header-footer.js" type="text/javascript" defer="defer"></script>


<script type="text/javascript" src="https://pages.nist.gov/leaveNotice/js/jquery.leaveNotice-nist.min.js"></script>
<script>
$(document).ready(function(){
  // Mark external (non-nist.gov) A tags with class "external"
  //If the adress start with https and ends with nist.gov
  var re_nist = new RegExp('^https?:\/\/((^\/)*\.)*nist\\.gov(\/|$)');
  //Regex to find address that start with https
  var re_absolute_address = new RegExp('^((https?:)?\/\/)');
  $("a").each(function(){
    var url=$(this).attr('href');
    if(re_nist.test(url) || !re_absolute_address.test(url)){
      $(this).addClass('local');
    }else{
      //This a href appears to be external, so tag it
      $(this).addClass('external');
    }
  });
  // Add leaveNotice to external A elements
  $('a.external').leaveNotice();
});
</script>
<link rel="stylesheet" type="text/css" href="https://pages.nist.gov/leaveNotice/css/jquery.leaveNotice.css" />
{% endblock %}