Skip to content

Commit 995e63f

Browse files
felixfonteinfelixfontein
authored
Merge pull request #20 from felixfontein/contribution-guidelines
Update contribution guidelines and README
2 parents 15bd478 + e745bc3 commit 995e63f

2 files changed

Lines changed: 25 additions & 212 deletions

File tree

‎README.md‎

Lines changed: 5 additions & 182 deletions
Original file line numberDiff line numberDiff line change
@@ -1,184 +1,7 @@
1-
# Docsy Example
1+
# SOPS Documentation Site
22

3-
[Docsy][] is a [Hugo theme module][] for technical documentation sites, providing easy
4-
site navigation, structure, and more. This **Docsy Example Project** uses the Docsy
5-
theme component as a hugo module and provides a skeleton documentation structure for you to use.
6-
You can clone/copy this project and edit it with your own content, or use it as an example.
3+
[SOPS](github.com/getsops/sops) is an open source secrets manager.
4+
This repository contains the documentation site for SOPS hosted at [getsops.io](https://getsops.io/).
75

8-
In this project, the Docsy theme is pulled in as a Hugo module, together with
9-
its dependencies:
10-
11-
```console
12-
$ hugo mod graph
13-
...
14-
```
15-
16-
For Docsy documentation, see [Docsy user guide][].
17-
18-
This Docsy Example Project is hosted on [Netlify][] at [example.docsy.dev][].
19-
You can view deploy logs from the [deploy section of the project's Netlify
20-
dashboard][deploys], or this [alternate dashboard][].
21-
22-
This is not an officially supported Google product. This project is currently maintained.
23-
24-
## Using the Docsy Example Project as a template
25-
26-
A simple way to get started is to use this project as a template, which gives you a site project that is set up and ready to use. To do this:
27-
28-
1. Use the dropdown for switching branches/tags to change to the **latest** released tag.
29-
30-
2. Click **Use this template**.
31-
32-
3. Select a name for your new project and click **Create repository from template**.
33-
34-
4. Make your own local working copy of your new repo using git clone, replacing https://github.com/me/example.git with your repo’s web URL:
35-
36-
```bash
37-
git clone --depth 1 https://github.com/me/example.git
38-
```
39-
40-
You can now edit your own versions of the site’s source files.
41-
42-
If you want to do SCSS edits and want to publish these, you need to install `PostCSS`
43-
44-
```bash
45-
npm install
46-
```
47-
48-
## Running the website locally
49-
50-
Building and running the site locally requires a recent `extended` version of [Hugo](https://gohugo.io).
51-
You can find out more about how to install Hugo for your environment in our
52-
[Getting started](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation) guide.
53-
54-
Once you've made your working copy of the site repo, from the repo root folder, run:
55-
56-
```bash
57-
hugo server
58-
```
59-
60-
## Running a container locally
61-
62-
You can run docsy-example inside a [Docker](https://docs.docker.com/)
63-
container, the container runs with a volume bound to the `docsy-example`
64-
folder. This approach doesn't require you to install any dependencies other
65-
than [Docker Desktop](https://www.docker.com/products/docker-desktop) on
66-
Windows and Mac, and [Docker Compose](https://docs.docker.com/compose/install/)
67-
on Linux.
68-
69-
1. Build the docker image
70-
71-
```bash
72-
docker-compose build
73-
```
74-
75-
1. Run the built image
76-
77-
```bash
78-
docker-compose up
79-
```
80-
81-
> NOTE: You can run both commands at once with `docker-compose up --build`.
82-
83-
1. Verify that the service is working.
84-
85-
Open your web browser and type `http://localhost:1313` in your navigation bar,
86-
This opens a local instance of the docsy-example homepage. You can now make
87-
changes to the docsy example and those changes will immediately show up in your
88-
browser after you save.
89-
90-
### Cleanup
91-
92-
To stop Docker Compose, on your terminal window, press **Ctrl + C**.
93-
94-
To remove the produced images run:
95-
96-
```bash
97-
docker-compose rm
98-
```
99-
For more information see the [Docker Compose documentation][].
100-
101-
## Using a local Docsy clone
102-
103-
Make sure your installed go version is `1.18` or higher.
104-
105-
Clone the latest version of the docsy theme into the parent folder of your project. The newly created repo should now reside in a sibling folder of your site's root folder.
106-
107-
```shell
108-
cd root-of-your-site
109-
git clone --branch v0.7.2 https://github.com/google/docsy.git ../docsy
110-
```
111-
112-
Now run:
113-
114-
```shell
115-
HUGO_MODULE_WORKSPACE=docsy.work hugo server --ignoreVendorPaths "**"
116-
```
117-
118-
or, when using npm, prepend `local` to the script you want to invoke, e.g.:
119-
120-
```shell
121-
npm run local serve
122-
```
123-
124-
By using the `HUGO_MODULE_WORKSPACE` directive (either directly or via prefix `local` when using npm), the server now watches all files and directories inside the sibling directory `../docsy` , too. Any changes inside the local `docsy` theme clone are now immediately picked up (hot reload), you can instantly see the effect of your local edits.
125-
126-
In the command above, we used the environment variable `HUGO_MODULE_WORKSPACE` to tell hugo about the local workspace file `docsy.work`. Alternatively, you can declare the workspace file inside your settings file `hugo.toml`:
127-
128-
```toml
129-
[module]
130-
workspace = "docsy.work"
131-
```
132-
133-
Your project's `hugo.toml` file already contains these lines, the directive for workspace assignment is commented out, however. Remove the two trailing comment characters '//' so that this line takes effect.
134-
135-
## Troubleshooting
136-
137-
As you run the website locally, you may run into the following error:
138-
139-
```console
140-
$ hugo server
141-
WARN 2023/06/27 16:59:06 Module "project" is not compatible with this Hugo version; run "hugo mod graph" for more information.
142-
Start building sites …
143-
hugo v0.101.0-466fa43c16709b4483689930a4f9ac8add5c9f66+extended windows/amd64 BuildDate=2022-06-16T07:09:16Z VendorInfo=gohugoio
144-
Error: Error building site: "C:\Users\foo\path\to\docsy-example\content\en\_index.md:5:1": failed to extract shortcode: template for shortcode "blocks/cover" not found
145-
Built in 27 ms
146-
```
147-
148-
This error occurs if you are running an outdated version of Hugo. As of docsy theme version `v0.7.0`, hugo version `0.110.0` or higher is required.
149-
See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) of the user guide for instructions on how to install Hugo.
150-
151-
Or you may be confronted with the following error:
152-
153-
```console
154-
$ hugo server
155-
156-
INFO 2021/01/21 21:07:55 Using config file:
157-
Building sites … INFO 2021/01/21 21:07:55 syncing static files to /
158-
Built in 288 ms
159-
Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): resource "scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68" not found in file cache
160-
```
161-
162-
This error occurs if you have not installed the extended version of Hugo.
163-
See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) of the user guide for instructions on how to install Hugo.
164-
165-
Or you may encounter the following error:
166-
167-
```console
168-
$ hugo server
169-
170-
Error: failed to download modules: binary with name "go" not found
171-
```
172-
173-
This error occurs if you have not installed the `go` programming language on your system.
174-
See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-go-language) of the user guide for instructions on how to install `go`.
175-
176-
177-
[alternate dashboard]: https://app.netlify.com/sites/goldydocs/deploys
178-
[deploys]: https://app.netlify.com/sites/docsy-example/deploys
179-
[Docsy user guide]: https://docsy.dev/docs
180-
[Docsy]: https://github.com/google/docsy
181-
[example.docsy.dev]: https://example.docsy.dev
182-
[Hugo theme module]: https://gohugo.io/hugo-modules/use-modules/#use-a-module-for-a-theme
183-
[Netlify]: https://netlify.com
184-
[Docker Compose documentation]: https://docs.docker.com/compose/gettingstarted/
6+
If you are interested in contributing to the documentation,
7+
look at [the contribution guidelines on the getsops.io](https://getsops.io/docs/contribution-guidelines).

‎content/en/docs/contribution-guidelines/_index.md‎

Lines changed: 20 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,14 @@
11
---
22
title: Contribution Guidelines
33
weight: 10
4-
description: How to contribute to the docs
5-
draft: true
4+
description: How to contribute to SOPS
65
---
76

8-
{{% pageinfo %}}
9-
These basic sample guidelines assume that your Docsy site is deployed using Netlify and your files are stored in GitHub. You can use the guidelines "as is" or adapt them with your own instructions: for example, other deployment options, information about your doc project's file structure, project-specific review guidelines, versioning guidelines, or any other information your users might find useful when updating your site. [Kubeflow](https://github.com/kubeflow/website/blob/master/README.md) has a great example.
7+
## Code contributions
108

11-
Don't forget to link to your own doc repo rather than our example site! Also make sure users can find these guidelines from your doc repo README: either add them there and link to them from this page, add them here and link to them from the README, or include them in both locations.
12-
{{% /pageinfo %}}
9+
Check out [CONTRIBUTING.md in the getsops/sops GitHub repository](https://github.com/getsops/sops/blob/main/CONTRIBUTING.md).
10+
11+
## Documentation contributions
1312

1413
We use [Hugo](https://gohugo.io/) to format and generate our website, the
1514
[Docsy](https://github.com/google/docsy) theme for styling and site structure,
@@ -23,58 +22,49 @@ use GitHub pull requests for this purpose. Consult
2322
[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
2423
information on using pull requests.
2524

26-
## Quick start with Netlify
25+
### Quick start with Netlify
2726

2827
Here's a quick guide to updating the docs. It assumes you're familiar with the
2928
GitHub workflow and you're happy to use the automated preview of your doc
3029
updates:
3130

32-
1. Fork the [Goldydocs repo](https://github.com/google/docsy-example) on GitHub.
31+
1. Fork the [getsops/docs repo](https://github.com/getsops/docs) on GitHub.
3332
1. Make your changes and send a pull request (PR).
34-
1. If you're not yet ready for a review, add "WIP" to the PR name to indicate
35-
it's a work in progress. (**Don't** add the Hugo property
36-
"draft = true" to the page front matter, because that prevents the
37-
auto-deployment of the content preview described in the next point.)
38-
1. Wait for the automated PR workflow to do some checks. When it's ready,
39-
you should see a comment like this: **deploy/netlify — Deploy preview ready!**
40-
1. Click **Details** to the right of "Deploy preview ready" to see a preview
41-
of your updates.
42-
1. Continue updating your doc and pushing your changes until you're happy with
43-
the content.
44-
1. When you're ready for a review, add a comment to the PR, and remove any
45-
"WIP" markers.
46-
47-
## Updating a single page
33+
1. If you're not yet ready for a review, add "WIP" to the PR name to indicate it's a work in progress.
34+
1. Wait for the automated PR workflow to do some checks. When it's ready, you should see a comment like this: **deploy/netlify — Deploy preview ready!**
35+
1. Click **Details** to the right of "Deploy preview ready" to see a preview of your updates.
36+
1. Continue updating your doc and pushing your changes until you're happy with the content.
37+
1. When you're ready for a review, add a comment to the PR, and remove any "WIP" markers.
38+
39+
### Updating a single page
4840

4941
If you've just spotted something you'd like to change while using the docs, Docsy has a shortcut for you:
5042

5143
1. Click **Edit this page** in the top right hand corner of the page.
5244
1. If you don't already have an up to date fork of the project repo, you are prompted to get one - click **Fork this repository and propose changes** or **Update your Fork** to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.
5345
1. Follow the rest of the [Quick start with Netlify](#quick-start-with-netlify) process above to make, preview, and propose your changes.
5446

55-
## Previewing your changes locally
47+
### Previewing your changes locally
5648

5749
If you want to run your own local Hugo server to preview your changes as you work:
5850

5951
1. Follow the instructions in [Getting started](/docs/getting-started) to install Hugo and any other tools you need. You'll need at least **Hugo version 0.45** (we recommend using the most recent available version), and it must be the **extended** version, which supports SCSS.
60-
1. Fork the [Goldydocs repo](https://github.com/google/docsy-example) repo into your own project, then create a local copy using `git clone`. Don’t forget to use `--recurse-submodules` or you won’t pull down some of the code you need to generate a working site.
52+
1. Fork the [getsops/docs repo](https://github.com/getsops/docs) repo into your own project, then create a local copy using `git clone`.
6153

6254
```
63-
git clone --recurse-submodules --depth 1 https://github.com/google/docsy-example.git
55+
git clone --depth 1 https://github.com/getsops/docs.git
6456
```
6557
6658
1. Run `hugo server` in the site root directory. By default your site will be available at http://localhost:1313/. Now that you're serving your site locally, Hugo will watch for changes to the content and automatically refresh your site.
6759
1. Continue with the usual GitHub workflow to edit files, commit them, push the
6860
changes up to your fork, and create a pull request.
6961
70-
## Creating an issue
62+
### Creating an issue
7163
72-
If you've found a problem in the docs, but you're not sure how to fix it yourself, please create an issue in the [Goldydocs repo](https://github.com/google/docsy-example/issues). You can also create an issue about a specific page by clicking the **Create Issue** button in the top right hand corner of the page.
64+
If you've found a problem in the docs, but you're not sure how to fix it yourself, please create an issue in the [sops-docs repo](https://github.com/getsops/docs/issues). You can also create an issue about a specific page by clicking the **Create Issue** button in the top right hand corner of the page.
7365
74-
## Useful resources
66+
### Useful resources
7567
7668
* [Docsy user guide](https://www.docsy.dev/docs/): All about Docsy, including how it manages navigation, look and feel, and multi-language support.
7769
* [Hugo documentation](https://gohugo.io/documentation/): Comprehensive reference for Hugo.
7870
* [Github Hello World!](https://guides.github.com/activities/hello-world/): A basic introduction to GitHub concepts and workflow.
79-
80-

0 commit comments

Comments
 (0)