From 680156c033b444f01d7b7d0cc8975bb65f3edd5d Mon Sep 17 00:00:00 2001 From: Graham Markall Date: Thu, 4 May 2023 13:25:51 +0100 Subject: [PATCH] Remove old Website development documentation We now use Readthedocs for the documentation, so the scripts and documentation relating to building and pushing docs to the Github pages is obsolete. In addition, the website is now served from a new repository. --- MANIFEST.in | 1 - docs/gh-pages.py | 150 ------------------------- docs/source/developer/contributing.rst | 30 +---- docs/source/developer/repomap.rst | 2 - 4 files changed, 1 insertion(+), 182 deletions(-) delete mode 100644 docs/gh-pages.py diff --git a/MANIFEST.in b/MANIFEST.in index 449dab31c5c..cb155875496 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -6,5 +6,4 @@ recursive-include docs *.ipynb *.txt *.py Makefile *.rst recursive-include examples *.py prune docs/_build -prune docs/gh-pages include numba/_version.py diff --git a/docs/gh-pages.py b/docs/gh-pages.py deleted file mode 100644 index 3c8093d0661..00000000000 --- a/docs/gh-pages.py +++ /dev/null @@ -1,150 +0,0 @@ -#!/usr/bin/env python -# -*- coding: utf-8 -*- -"""Script to commit the doc build outputs into the github-pages repo. - -Use: - - gh-pages.py [tag] - -If no tag is given, the current output of 'git describe' is used. If given, -that is how the resulting directory will be named. - -In practice, you should use either actual clean tags from a current build or -something like 'current' as a stable URL for the most current version of the """ -from __future__ import print_function, division, absolute_import - -#----------------------------------------------------------------------------- -# Imports -#----------------------------------------------------------------------------- -import os -import re -import shutil -import sys -from os import chdir as cd -from os.path import join as pjoin - -from subprocess import Popen, PIPE, CalledProcessError, check_call - -#----------------------------------------------------------------------------- -# Globals -#----------------------------------------------------------------------------- - -pages_dir = 'gh-pages' -html_dir = '_build/html' -pdf_dir = '_build/latex' -pages_repo = 'git@github.com:numba/numba-doc.git' - -#----------------------------------------------------------------------------- -# Functions -#----------------------------------------------------------------------------- -def sub_environment(): - """Return an environment dict for executing subcommands in.""" - env = os.environ.copy() - # Force untranslated messages for regex matching - env['LANG'] = 'C' - return env - - -def sh(cmd): - """Execute command in a subshell, return status code.""" - return check_call(cmd, shell=True, env=sub_environment()) - - -def sh2(cmd): - """Execute command in a subshell, return stdout. - - Stderr is unbuffered from the subshell.x""" - p = Popen(cmd, stdout=PIPE, shell=True, env=sub_environment()) - out = p.communicate()[0] - retcode = p.returncode - if retcode: - raise CalledProcessError(retcode, cmd) - else: - return out.rstrip() - - -def sh3(cmd): - """Execute command in a subshell, return stdout, stderr - - If anything appears in stderr, print it out to sys.stderr""" - p = Popen(cmd, stdout=PIPE, stderr=PIPE, shell=True, - env=sub_environment()) - out, err = p.communicate() - retcode = p.returncode - if retcode: - raise CalledProcessError(retcode, cmd) - else: - return out.rstrip(), err.rstrip() - - -def init_repo(path): - """clone the gh-pages repo if we haven't already.""" - sh("git clone %s %s"%(pages_repo, path)) - here = os.getcwd() - cd(path) - sh('git checkout gh-pages') - cd(here) - -#----------------------------------------------------------------------------- -# Script starts -#----------------------------------------------------------------------------- -if __name__ == '__main__': - # The tag can be given as a positional argument - try: - tag = sys.argv[1] - except IndexError: - try: - tag = sh2('git describe --exact-match').decode() - except CalledProcessError: - tag = "dev" # Fallback - print("Using dev") - - startdir = os.getcwd() - if not os.path.exists(pages_dir): - # init the repo - init_repo(pages_dir) - else: - # ensure up-to-date before operating - cd(pages_dir) - sh('git checkout gh-pages') - sh('git pull') - cd(startdir) - - dest = pjoin(pages_dir, tag) - - # don't `make html` here, because gh-pages already depends on html in Makefile - # sh('make html') - if tag != 'dev': - # only build pdf for non-dev targets - #sh2('make pdf') - pass - - # This is pretty unforgiving: we unconditionally nuke the destination - # directory, and then copy the html tree in there - shutil.rmtree(dest, ignore_errors=True) - shutil.copytree(html_dir, dest) - if tag != 'dev': - #shutil.copy(pjoin(pdf_dir, 'ipython.pdf'), pjoin(dest, 'ipython.pdf')) - pass - - try: - cd(pages_dir) - status = sh2('git status | head -1').decode() - branch = re.match('\#?\s*On branch (.*)$', status).group(1) - if branch != 'gh-pages': - e = 'On %r, git branch is %r, MUST be "gh-pages"' % (pages_dir, - branch) - raise RuntimeError(e) - - sh('git add -A %s' % tag) - sh('git commit -m"Updated doc release: %s"' % tag) - print() - print('Most recent 3 commits:') - sys.stdout.flush() - sh('git --no-pager log --oneline HEAD~3..') - finally: - cd(startdir) - - print() - print('Now verify the build in: %r' % dest) - print("If everything looks good, 'git push'") diff --git a/docs/source/developer/contributing.rst b/docs/source/developer/contributing.rst index af39471a06e..d266cbc688b 100644 --- a/docs/source/developer/contributing.rst +++ b/docs/source/developer/contributing.rst @@ -475,39 +475,11 @@ build and check the documentation:: $ make html $ open _build/html/index.html -Core developers can upload this documentation to the Numba website -at https://numba.pydata.org by using the ``gh-pages.py`` script under ``docs``:: - - $ python gh-pages.py version # version can be 'dev' or '0.16' etc - -then verify the repository under the ``gh-pages`` directory and use -``git push``. - Web site homepage ''''''''''''''''' The Numba homepage on https://numba.pydata.org can be fetched from here: -https://github.com/numba/numba-webpage - -After pushing documentation to a new version, core developers will want to -update the website. Some notable files: - -* ``index.rst`` # Update main page -* ``_templates/sidebar_versions.html`` # Update sidebar links -* ``doc.rst`` # Update after adding a new version for numba docs -* ``download.rst`` # Updata after uploading new numba version to pypi - -After updating run:: - - $ make html - -and check out ``_build/html/index.html``. To push updates to the Web site:: - - $ python _scripts/gh-pages.py - -then verify the repository under the ``gh-pages`` directory. Make sure the -``CNAME`` file is present and contains a single line for ``numba.pydata.org``. -Finally, use ``git push`` to update the website. +https://github.com/numba/numba.github.com .. _typeguard: https://typeguard.readthedocs.io/en/latest/ diff --git a/docs/source/developer/repomap.rst b/docs/source/developer/repomap.rst index f42194b229d..4158be285f2 100644 --- a/docs/source/developer/repomap.rst +++ b/docs/source/developer/repomap.rst @@ -51,8 +51,6 @@ Documentation - :ghfile:`docs/Makefile` - Used to build Sphinx docs with ``make`` - :ghfile:`docs/source` - ReST source for Numba documentation - :ghfile:`docs/_static/` - Static CSS and image assets for Numba docs -- :ghfile:`docs/gh-pages.py` - Utility script to update Numba docs (stored - as gh-pages) - :ghfile:`docs/make.bat` - Not used (remove?) - :ghfile:`docs/requirements.txt` - Pip package requirements for building docs with Read the Docs.