Move to Hugo + other improvements (#38)

* Hugo-ify and reorganize files

* Enforce editorconfig formatting

* Bump Bootstrap version to beta-3

* Add alert shortcode

* Fix missing fa icons

* Add sidebar menu items

* Add support for custom 404

* Convert all RestructuredText to Markdown

* Clean up old files

* Re-add license

* Update README

* Update .htaccess with old redirects

* Update sidebar menu items

* Add new layout and styling classes

* Move tutorials into their dedicated folder

* Move .htaccess to static folder

* Add helper list partials

* Add sidebar generation logic

* Add content to home page

* Move scripts to a partial

* Update spacing styling in footer

* Add docs layout & new sidebar pages

* Update README & config

* Tidy up stylesheet

* Tidy up Markdown files + add front matter

* Add archetypes

* Update README and site config

* Add & fix new sidebar items

* Complete home layout

* Improve help and support callout

* Fix the sidebar

* Make a few minor corrections + syntax fixes

* Fix line breaks in template tags

* Improve content readability

* Fix group parameter and slug for some pages

* Improve styling of code blocks

* Fix "introduction" index pages

* Add internal docs

* Update code block styles

* Reduce toc nesting level to 3

* Add docs on docs

* Fix fence block language

* Update .gitignore

* Make minor improvements to templates

* Add toc support

* Make some minor text changes

* Tidy up all tutorials

* Update tutorials template

* Update reference

* Tidy up guides

* Add table shortcode

* Add subnav

* Add redirects

* Add PDF export ability

* Make some minor touch ups

* Add new user params in config

* Add cache dir for build

* Swap absolute links to relative

* Remove dropdowns from sidebar

* Improve commit messages at end of pages

* Fix typo and styles for footer

* Comment out search while it is not used

* Update CI

* Revise PDF guidance

* Don't build directly to _docs

* Don't vendor fontawesome

* Set sensible default for build dir

* Don't sync times for builds

.github/FUNDING.yml

@@ -1,3 +1,3 @@
 # These are supported funding model platforms
 
-custom: ['https://www.srcf.net/donate']
+custom: ["https://www.srcf.net/donate"]

.github/workflows/ci.yml

@@ -8,14 +8,4 @@ jobs:
     steps:
       - name: Checkout code
         if: contains(github.event.head_commit.message, 'skip ci') == false
-        uses: actions/checkout@v1
-      - name: Set up Python 
-        uses: actions/setup-python@v2
-        with:
-          python-version: '3.x'
-      - name: Install dependencies
-        run: pip install -r requirements.txt
-      - name: Create Makefile.local
-        run: touch Makefile.local
-      - name: Check that HTML output can be built
-        run: make html
+        uses: actions/checkout@v1

.gitignore

@@ -4,3 +4,4 @@ Makefile.local
 .vscode
 .idea/
 .venv/
+public/*

Makefile

@@ -1,19 +1,14 @@
-# Minimal makefile for Sphinx documentation
-#
+BUILDDIR ?= public
+CACHEDIR = $(shell mktemp -d)
 
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = build
+all: clean build
 
--include Makefile.local
+.PHONY: build
+build:
+	hugo -d $(BUILDDIR) --cacheDir $(CACHEDIR) --noTimes
+	rm -rf $(CACHEDIR)
 
-default: html
-.PHONY: default 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)
+.PHONY: clean
+clean:
+	rm -rf $(BUILDDIR)/*

README.md

@@ -1,18 +1,18 @@
-# docs
-A repository for SRCF documentation.
+# SRCF Documentation
 
-## Building
+This is the Git repository for the SRCF's documentation, available at [docs.srcf.net](https://docs.srcf.net). It is built with Hugo, a static site generator written in Go. You can read, contribute and build these docs yourself, just keep reading!
 
-Windows: `./make.bat html`
+The previous iteration of our documentation was built with Sphinx, but after facing several shortcomings we decided to move to a static site generator.
 
-Linux/macOS: `make html`
+## Contributing
 
-## Setting the output path
+All contributions to our documentation are very welcome. We have more detailed information for beginners and advanced users alike on our [internal documentation](https://docs.srcf.net/internal/documentation/building/).
 
-1.  Create a file `Makefile.local` in the root of this repository.  This is an
-    optional snippet of Makefile that is automatically sourced in the main
-    Makefile.
+### TODO
 
-2.  Set variables, e.g.:
+* add search
+* vendor static assets centrally
 
-        BUILDDIR = /public/home/spqr2/srcf-docs
+## Credits
+
+This documentation is largely inspired by [Bootstrap](https://github.com/twbs/bootstrap/).

archetypes/default.md

@@ -0,0 +1,7 @@
+---
+title: "{{ replace .Name "-" " " | title }}"
+date: {{ .Date }}
+group:
+layout: docs
+---
+

archetypes/tutorials.md

@@ -0,0 +1,21 @@
+---
+title: "{{ replace .Name "-" " " | title }}"
+date: {{ .Date }}
+group:
+layout: docs
+toc: true
+---
+
+## Overview
+
+## Introduction
+
+## Closing remarks
+
+Did you like this or find this cool? We invite you to check out
+[more tutorials]({{< relref "/tutorials" >}})
+or [get in touch]({{< relref "/#help-and-support" >}}) to tell us what you thought!
+
+If you have any suggestions for how we could improve this documentation
+please send us an email at `support@srcf.net` or submit a Pull Request
+on [GitHub](https://github.com/SRCF/docs)!

config.toml

@@ -0,0 +1,22 @@
+baseURL = "http://docs.srcf.net"
+languageCode = "en-us"
+title = "SRCF Documentation"
+
+disableKinds = ["taxonomy", "term"]
+
+# see motivation in README
+uglyURLs = false
+enableGitInfo = true
+
+[markup]
+  [markup.tableOfContents]
+    endLevel = 3
+    startLevel = 2
+
+[params]
+    domain_web = "https://www.srcf.net"
+    domain_control = "https://control.srcf.net"
+    description = "The Student-Run Computing Facility is a volunteer-run student society that provides free, useful and flexible computing and network services for Cambridge University staff and students of all degrees of ability."
+    repo = "https://github.com/matiasilva/docs"
+    repo_branch = "move-to-hugo"
+    pdf_path = "docs.pdf"

content/_index.md

@@ -0,0 +1,4 @@
+---
+title: "Home"
+date: 2021-04-20T09:27:49+01:00
+---

content/all.md

@@ -0,0 +1,5 @@
+---
+title: Reader-friendly docs
+date: 2021-04-20T09:27:49+01:00
+layout: all
+---

content/guides/_index.md

@@ -0,0 +1,8 @@
+---
+title: "Guides"
+date: 2021-04-20T09:27:49+01:00
+group: introduction
+layout: docs
+---
+
+These are the Guides that the SRCF has produced for its services.

content/guides/getting-started-groups.md

@@ -0,0 +1,7 @@
+---
+title: "Getting Started: Groups"
+date: 2021-04-19T23:50:47+01:00
+layout: docs
+group: getting-started-groups
+---
+

content/guides/getting-started-users.md

@@ -0,0 +1,10 @@
+---
+title: "Getting Started: Users"
+date: 2021-04-19T23:50:28+01:00
+layout: docs
+group: getting-started-users
+---
+
+To start with, you'll need to [create a personal
+account](https://control.srcf.net/signup). This will allow you to use
+the control panel to add more services.

content/guides/society-handovers.md

@@ -0,0 +1,7 @@
+---
+title: "Society Handovers"
+date: 2021-04-19T23:52:13+01:00
+layout: docs
+group: society-handovers
+---
+

content/guides/upgrade-guidance/drupal.md

@@ -0,0 +1,74 @@
+---
+title: "Upgrading a Drupal installation"
+date: 2021-04-21T16:44:31+01:00
+group: upgrade-guidance
+layout: docs
+---
+
+## Overview
+
+{{< alert type="info" >}}
+Version 6 releases are no longer supported by Drupal, and are liable to
+have compatibility issues with PHP 7.
+{{<  /alert >}}
+
+The notes below assume your Drupal site is at `drupal.soc.srcf.net` \--
+substitute this for your own site's URL.
+
+Drupal provide [their own extensive guide for
+upgrades](https://www.drupal.org/updating-and-upgrading-drupal-core),
+which covers the below information in more detail.
+
+## Upgrading files in-place
+
+This method is suitable for minor version upgrades (e.g. from an old 7.x
+to the latest 7.x release). See also: [Update procedure (minor version
+change)](https://www.drupal.org/docs/8/upgrade/upgrading-from-drupal-6-or-7-to-drupal-8)
+
+**Take backups of your files and database before attempting an
+upgrade.** Then put the site into maintenance mode.
+
+Download the latest release from <https://www.drupal.org/download>. The
+ZIP file contains a folder called `drupal-<version>`, which contains the
+core files.
+
+If you\'re working over SSH, copy the URL of the ZIP download, use
+`wget` to download it, then `unzip` to unpack it in the current
+directory.
+
+For SCP, you\'ll want to extract the files on your local machine, then
+upload them to the server.
+
+In either case, the contents of the `drupal` folder are to be moved into
+your existing site (for `drupal.soc.srcf.net`, this would be
+`/societies/drupal/public_html`). You should delete all files under the
+site directory, \'\'\'except\'\'\' the `sites` folder which holds all
+customisations. If you\'ve made any changes to `.htaccess` or
+`robots.txt`, you\'ll also need to merge these into the updated files.
+
+Once the new files are in place, head over to
+`http://drupal.soc.srcf.net/update.php` to prepare the database for the
+new version. When complete, take the site out of maintenance mode.
+
+Migrating a site between instances
+----------------------------------
+
+This is needed for major release upgrades (e.g. from 7.x to 8.x).
+
+Similar to the above, download the latest version, but extract/upload it
+to a different location than the current site. Configure this as a new
+installation. It still needs to be under your account\'s `public_html`
+root, so you may need to use a subdirectory. This page assumes you have
+`http://drupal.soc.srcf.net/new/`.
+
+Go to the \'\'Modules\'\' section on the new site, and enable the
+\'\'Migrate\'\', \'\'Migrate Drupal\'\', and \'\'Migrate Drupal UI\'\'
+modules.
+
+Now head over to `http://drupal.soc.srcf.net/new/upgrade`, which will
+prompt for database credentials \-- here, you can specify those of the
+old site, which will import all its content into the new installation.
+
+Once you\'re happy the new site is working, you can move the old one out
+of the way and make the new site take its place. You\'ll need to update
+the `$base_url` in `settings.php` with the new path.

content/guides/upgrade-guidance/focal-changes.md

@@ -0,0 +1,113 @@
+---
+title: "Changes in 20.04 Focal"
+date: 2021-04-21T16:44:31+01:00
+group: upgrade-guidance
+layout: docs
+toc: true
+---
+
+{{< alert type="warning" >}}
+These notes relate to the migration from Ubuntu 16.04 to 20.04,
+scheduled for 3rd/4th April 2021.{{<  /alert >}}
+
+## Server changes
+
+The following shell-accessible servers, currently on Ubuntu 16.04
+\'Xenial Xerus\', will be upgraded to 20.04 \'Focal Fossa\':
+
+- `pip` (aka. *shell.srcf.net*), the main shell server
+- `sinkhole` (aka. *webserver.srcf.net*), the web server
+
+As we already have `doom`, a 20.04 server for games and long-running
+processes, we\'ll be decommissioning the old games server `cavein`
+shortly after the upgrade. Please migrate your servers and scheduled
+tasks ahead of the upgrade.
+
+We\'ll also be upgrading other servers hosting various SRCF services,
+which will experience some downtime:
+
+- `blizzard`, the DNS server (though access to other services on the
+    *srcf.net* domain will be unaffected by this)
+- `flame`, the news server
+- `squirrel`, the MySQL server
+
+## Software updates
+
+If you'd like to check what version of a particular package will be
+installed after the upgrade, you can search for it on the [Ubuntu
+package directory](https://packages.ubuntu.com). If a package is listed
+for `xenial`, but not for `focal`, then it is liable to be removed
+following the upgrade \-- [contact the
+sysadmins](https://www.srcf.net/contact) if there\'s a package you need
+that\'s slated for removal, and we can see what can be done.
+
+{{< table "table table-striped" >}}
+| Name       | Current version | New version | Links                                                                          |
+| ---------- | --------------- | ----------- | ------------------------------------------------------------------------------ |
+| Apache     | 2.4.18          | 2.4.41      | [CHANGES file](https://github.com/apache/httpd/blob/2.4.41/CHANGES)            |
+| MySQL      | 5.5             | 8.0         | [Release Notes](https://dev.mysql.com/doc/relnotes/mysql/8.0/en/)              |
+| Node.js    | 4.2.6           | 10.19.0     | [Changelogs](https://github.com/nodejs/node/tree/v10.19.0/doc/changelogs)      |
+| PHP        | 7.0             | 7.4         | [Appendices (Migrating from...)](https://www.php.net/manual/en/appendices.php) |
+| PostgreSQL | 9.5             | 12          | [Release Notes](https://www.postgresql.org/docs/release/)                      |
+| Python     | 3.5             | 3.8         | [What\'s New in Python](https://docs.python.org/3.8/whatsnew/index.html)       |
+| Ruby       | 2.3             | 2.7         | [Ruby Releases](https://www.ruby-lang.org/en/downloads/releases/)              |
+{{< /table >}}
+
+If you\'ve built or compiled your own software linked to libraries on
+the system, you\'ll likely need to recompile them following the upgrade.
+
+### Python 2
+
+The majority of Python 2 packages have been dropped by Ubuntu, leaving
+only a handful of libraries acting as dependencies for packaged software
+that doesn\'t run on Python 3. If you\'re running your own software with
+py2, you should seek to make it compatible with py3 \-- official support
+for py2 ended in January 2020, with setuptools, pip and other core
+components becoming py3-only.
+
+Failing that, the core interpreter is still available, along with the
+ability to create py2 virtual environments if you\'re currently relying
+on any system-installed py2 packages that will no longer be available.
+Beware of upgrading the build tools in such environments \-- the last
+version of pip to support py2 is 20.3, and for setuptools the last
+compatible release was 44.0.0.
+
+### Python 3
+
+Python 3 itself will receive a minor version bump from 3.5 to 3.8 \--
+the [What\'s New](https://docs.python.org/3/whatsnew/) section of the
+Python documentation lists all the changes between versions.
+
+The change in version also changes the library path, which means any
+packages user-installed to `~/.local/lib/python3.5` (with
+`pip install --user` or otherwise) will no longer be accessible and will
+need reinstalling following the upgrade. In addition, any virtual Python
+environments using the system copy of py3 will stop working, and will
+need recreating. Custom installations of Python (e.g. those installed
+with tools like [pyenv](https://github.com/pyenv/pyenv)) may also need
+reinstalling following system library updates.
+
+### PHP
+
+PHP will be updated from 7.0 to 7.4. A list of new features and
+backwards-incompatible changes can be found in [their
+documentation](https://www.php.net/manual/en/appendices.php).
+
+Notably, this introduces a number of new syntax features, such as arrow
+function shorthand and the null-safe `?.` operator. The majority of
+backwards-incompatible changes seem to cover previously unspecified or
+erroneous behaviour, though consult the *Backward Incompatible Changes*
+sections for all the details.
+
+### Node.js
+
+Node is being brought into the (relatively) modern times, to be updated
+from major version 4 to 10. The canonical binary name will change from
+`nodejs` to `node`, though the former will remain as a symlink.
+
+Unsurprisingly there will have been a number of additions and changes
+\-- Node\'s
+[changelogs](https://github.com/nodejs/node/tree/v10.19.0/doc/changelogs)
+cover all the details but are quite verbose; there\'s also [this list of
+breaking changes](https://github.com/WaleedAshraf/nodejs-major-changes)
+if you just want to check your code for compatibility.