Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
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
  • Loading branch information
matiasilva committed May 6, 2021
1 parent 88324e6 commit dec0895
Show file tree
Hide file tree
Showing 169 changed files with 6,828 additions and 4,485 deletions.
2 changes: 1 addition & 1 deletion .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"]
12 changes: 1 addition & 11 deletions .github/workflows/ci.yml
Expand Up @@ -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
1 change: 1 addition & 0 deletions .gitignore
Expand Up @@ -4,3 +4,4 @@ Makefile.local
.vscode
.idea/
.venv/
public/*
25 changes: 10 additions & 15 deletions 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)/*
22 changes: 11 additions & 11 deletions 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/).
7 changes: 7 additions & 0 deletions archetypes/default.md
@@ -0,0 +1,7 @@
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
group:
layout: docs
---

21 changes: 21 additions & 0 deletions 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)!
22 changes: 22 additions & 0 deletions 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"
4 changes: 4 additions & 0 deletions content/_index.md
@@ -0,0 +1,4 @@
---
title: "Home"
date: 2021-04-20T09:27:49+01:00
---
5 changes: 5 additions & 0 deletions content/all.md
@@ -0,0 +1,5 @@
---
title: Reader-friendly docs
date: 2021-04-20T09:27:49+01:00
layout: all
---
8 changes: 8 additions & 0 deletions 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.
7 changes: 7 additions & 0 deletions 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
---

10 changes: 10 additions & 0 deletions 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.
7 changes: 7 additions & 0 deletions 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
---

74 changes: 74 additions & 0 deletions 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.
113 changes: 113 additions & 0 deletions 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