Skip to content

Commit

Permalink
create doc sitemap.xml for development site and fix for master deploy…
Browse files Browse the repository at this point in the history
…ment

- sitemap.xml is appropriate for the development docs: thus we do not ship
  and install a sitemap.xml that is misleading (when installing automatically
  via Travis CI)
- change the loc in the sitemap.xml with the new maintainer/adapt_sitemap.py
  script: parse XML tree and replace the developer site URL prefix with the
  release doc prefix
- manually create the release docs from master with the
  maintainer/deploy_master_docs.sh script (which is now calling
  the adapt_sitemap.py script)
orbeckst committed May 7, 2018
1 parent 7d60bc5 commit 8bab359
Showing 3 changed files with 88 additions and 5 deletions.
64 changes: 64 additions & 0 deletions maintainer/adapt_sitemap.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
#!/usr/bin/env python
#
#
# Adjust path in sitemap.xml

from __future__ import print_function

from xml.etree import ElementTree
import argparse

# defaults for MDAnalysis, see https://github.com/MDAnalysis/mdanalysis/pull/1890
# and https://github.com/MDAnalysis/MDAnalysis.github.io/issues/78

RELEASE_URL = "https://www.mdanalysis.org/docs/"
DEVELOP_URL = "https://www.mdanalysis.org/mdanalysis/"

# change if sitemaps.org updates their schema
NAMESPACE = {"sitemaps": "http://www.sitemaps.org/schemas/sitemap/0.9"}

def replace_loc(tree, search, replace, namespace=NAMESPACE):
root = tree.getroot()
urls = root.findall("sitemaps:url", namespace)
if len(urls) == 0:
raise ValueError("No sitemaps:url element found: check if the namespace in the XML file "
"is still xmlns='{0[sitemaps]}'".format(namespace))
for url in urls:
loc = url.find("sitemaps:loc", namespace)
try:
loc.text = loc.text.replace(search, replace)
except AttributError:
raise ValueError("No sitemaps:loc element found: check if the namespace in the XML file "
"is still xmlns='{0[sitemaps]}'".format(namespace))
return tree


if __name__ == "__main__":
parser = argparse.ArgumentParser(description='Change top level loc in sitemap.',
formatter_class=argparse.ArgumentDefaultsHelpFormatter)

parser.add_argument('sitemap', metavar="FILE",
help="path to sitemap.xml file, will be changed in place")
parser.add_argument('--output', '-o', metavar="FILE",
default="sitemap_release.xml",
help="write altered XML to output FILE")
parser.add_argument("--search", "-s", metavar="URL",
default=DEVELOP_URL,
help="search this URL in the loc elements")
parser.add_argument("--replace", "-r", metavar="URL",
default=RELEASE_URL,
help="replace the searched URL with this URL in the loc elements")
args = parser.parse_args()


with open(args.sitemap) as xmlfile:
tree = ElementTree.parse(xmlfile)

tree = replace_loc(tree, args.search, args.replace)

with open(args.output, "wb") as xmlfile:
tree.write(xmlfile, encoding="utf-8", xml_declaration=True,
default_namespace=NAMESPACE['sitemaps'])

print("adapt_sitemap.py: Created output file {} with change in loc:".format(args.output))
print("adapt_sitemap.py: {0} --> {1}".format(args.search, args.replace))
20 changes: 19 additions & 1 deletion maintainer/deploy_master_docs.sh
Original file line number Diff line number Diff line change
@@ -25,6 +25,14 @@
# (cd package && python setup.py build_sphinx)
#

# The release sitemap.xml is generated from the development
# sitemap.xml by changing MDA_DEVELOPMENT_DOCS_URL --> MDA_RELEASE_DOCS_URL
#
# See comment in package/doc/sphinx/source/conf.py for site_url.
#
MDA_RELEASE_DOCS_URL="https://www.mdanalysis.org/docs/"
MDA_DEVELOPMENT_DOCS_URL="https://www.mdanalysis.org/mdanalysis/"

GH_REPOSITORY=github.com/MDAnalysis/docs.git
#MDA_DOCDIR=${TRAVIS_BUILD_DIR}/package/doc/html/html
MDA_DOCDIR=package/doc/html/html
@@ -44,6 +52,9 @@ function die () {
}

rev=$(git rev-parse --short HEAD)
rootdir="$(git rev-parse --show-toplevel)"

maintainer_dir="${rootdir}/maintainer"

# the following tests should be superfluous because of -o nounset
test -n "${GH_TOKEN}" || die "GH_TOKEN is empty: need OAuth GitHub token to continue" 100
@@ -60,14 +71,21 @@ git config user.name "${GIT_CI_USER}"
git config user.email "${GIT_CI_EMAIL}"

git remote add docs "https://${GH_TOKEN}@${GH_REPOSITORY}"
git fetch --depth 50 docs master
git fetch --depth 10 docs master
git reset docs/master

touch .
touch .nojekyll

git add -A .
git commit -m "rebuilt html docs from branch ${GH_DOC_BRANCH} with sphinx at MDAnalysis/mdanalysis@${rev}"

# fix sitemap.xml for release docs
${maintainer_dir}/adapt_sitemap.py --search ${MDA_DEVELOPMENT_DOCS_URL} --replace ${MDA_RELEASE_DOCS_URL} -o sitemap.xml sitemap.xml

git add sitemap.xml
git commit -m "adjusted sitemap.xml for release docs at ${MDA_RELEASE_DOCS_URL}"

git push -q docs HEAD:master


9 changes: 5 additions & 4 deletions package/doc/sphinx/source/conf.py
Original file line number Diff line number Diff line change
@@ -42,10 +42,11 @@
mathjax_path = 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML'

# for sitemap with https://github.com/jdillard/sphinx-sitemap
# NOTE: This sitemap is only correct for the release doccs. The development docs
# are served from https://www.mdanalysis.org/mdanalysis/ and the sitemap.xml
# will NOT be correct for the development docs.
site_url = "https://www.mdanalysis.org/docs/"
# NOTE: This sitemap is only correct for the DEVELOPMENT doccs. The RELEASE docs
# are served from https://www.mdanalysis.org/docs/ and the sitemap.xml
# is manually fixed when deploying the release docs with the
# maintainer/deploy_master_docs.sh script
site_url = "https://www.mdanalysis.org/mdanalysis/"

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

0 comments on commit 8bab359

Please sign in to comment.