Skip to content

Commit dec0895

Browse files
matiasilvamatiasilva
authored
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
1 parent 88324e6 commit dec0895

File tree

169 files changed

+6828
-4485
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

169 files changed

+6828
-4485
lines changed

‎.github/FUNDING.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
# These are supported funding model platforms
22

3-
custom: ['https://www.srcf.net/donate']
3+
custom: ["https://www.srcf.net/donate"]

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,4 @@ jobs:
88
steps:
99
- name: Checkout code
1010
if: contains(github.event.head_commit.message, 'skip ci') == false
11-
uses: actions/checkout@v1
12-
- name: Set up Python
13-
uses: actions/setup-python@v2
14-
with:
15-
python-version: '3.x'
16-
- name: Install dependencies
17-
run: pip install -r requirements.txt
18-
- name: Create Makefile.local
19-
run: touch Makefile.local
20-
- name: Check that HTML output can be built
21-
run: make html
11+
uses: actions/checkout@v1

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@ Makefile.local
44
.vscode
55
.idea/
66
.venv/
7+
public/*

‎Makefile‎

Lines changed: 10 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,14 @@
1-
# Minimal makefile for Sphinx documentation
2-
#
1+
BUILDDIR ?= public
2+
CACHEDIR = $(shell mktemp -d)
33

4-
# You can set these variables from the command line, and also
5-
# from the environment for the first two.
6-
SPHINXOPTS ?=
7-
SPHINXBUILD ?= sphinx-build
8-
SOURCEDIR = source
9-
BUILDDIR = build
4+
all: clean build
105

11-
-include Makefile.local
6+
.PHONY: build
7+
build:
8+
hugo -d $(BUILDDIR) --cacheDir $(CACHEDIR) --noTimes
9+
rm -rf $(CACHEDIR)
1210

13-
default: html
14-
.PHONY: default Makefile
1511

16-
# Catch-all target: route all unknown targets to Sphinx using the new
17-
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
18-
%: Makefile
19-
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
12+
.PHONY: clean
13+
clean:
14+
rm -rf $(BUILDDIR)/*

‎README.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
1-
# docs
2-
A repository for SRCF documentation.
1+
# SRCF Documentation
32

4-
## Building
3+
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!
54

6-
Windows: `./make.bat html`
5+
The previous iteration of our documentation was built with Sphinx, but after facing several shortcomings we decided to move to a static site generator.
76

8-
Linux/macOS: `make html`
7+
## Contributing
98

10-
## Setting the output path
9+
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/).
1110

12-
1. Create a file `Makefile.local` in the root of this repository. This is an
13-
optional snippet of Makefile that is automatically sourced in the main
14-
Makefile.
11+
### TODO
1512

16-
2. Set variables, e.g.:
13+
* add search
14+
* vendor static assets centrally
1715

18-
BUILDDIR = /public/home/spqr2/srcf-docs
16+
## Credits
17+
18+
This documentation is largely inspired by [Bootstrap](https://github.com/twbs/bootstrap/).

‎archetypes/default.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: "{{ replace .Name "-" " " | title }}"
3+
date: {{ .Date }}
4+
group:
5+
layout: docs
6+
---
7+

‎archetypes/tutorials.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: "{{ replace .Name "-" " " | title }}"
3+
date: {{ .Date }}
4+
group:
5+
layout: docs
6+
toc: true
7+
---
8+
9+
## Overview
10+
11+
## Introduction
12+
13+
## Closing remarks
14+
15+
Did you like this or find this cool? We invite you to check out
16+
[more tutorials]({{< relref "/tutorials" >}})
17+
or [get in touch]({{< relref "/#help-and-support" >}}) to tell us what you thought!
18+
19+
If you have any suggestions for how we could improve this documentation
20+
please send us an email at `support@srcf.net` or submit a Pull Request
21+
on [GitHub](https://github.com/SRCF/docs)!

‎config.toml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
baseURL = "http://docs.srcf.net"
2+
languageCode = "en-us"
3+
title = "SRCF Documentation"
4+
5+
disableKinds = ["taxonomy", "term"]
6+
7+
# see motivation in README
8+
uglyURLs = false
9+
enableGitInfo = true
10+
11+
[markup]
12+
[markup.tableOfContents]
13+
endLevel = 3
14+
startLevel = 2
15+
16+
[params]
17+
domain_web = "https://www.srcf.net"
18+
domain_control = "https://control.srcf.net"
19+
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."
20+
repo = "https://github.com/matiasilva/docs"
21+
repo_branch = "move-to-hugo"
22+
pdf_path = "docs.pdf"

‎content/_index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: "Home"
3+
date: 2021-04-20T09:27:49+01:00
4+
---

‎content/all.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: Reader-friendly docs
3+
date: 2021-04-20T09:27:49+01:00
4+
layout: all
5+
---

0 commit comments

Comments
 (0)