|
1 | | -# Docsy Example |
| 1 | +# About |
2 | 2 |
|
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 | +This repository contains sources for the poster "Portable data-parallel extensions with oneAPI" poster by [@ndgrigorian](https://github.com/ndgrigorian) for [EuroPython 2025](https://ep2025.europython.eu/), with examples co-written by [@oleksandr-pavlyk](https://github.com/oleksandr-pavlyk). |
7 | 4 |
|
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 | | -Depending on your environment you may need to adjust the top-level `module` settings in your project's Hugo config file, for example, by adding a proxy to use when downloading remote modules. |
41 | | -You can find details of what these configuration settings do in the [Hugo modules documentation](https://gohugo.io/hugo-modules/configuration/#module-config-top-level). |
42 | | - |
43 | | -Once your settings are adjusted, you can edit your own versions of the site’s source files. |
44 | | - |
45 | | -If you want to do SCSS edits and want to publish these, you need to install `PostCSS` |
46 | | - |
47 | | -```bash |
48 | | -npm install |
49 | | -``` |
50 | | - |
51 | | -## Running the website locally |
52 | | - |
53 | | -Building and running the site locally requires a recent `extended` version of [Hugo](https://gohugo.io). |
54 | | -You can find out more about how to install Hugo for your environment in our |
55 | | -[Getting started](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation) guide. |
56 | | - |
57 | | -Once you've made your working copy of the site repo, from the repo root folder, run: |
58 | | - |
59 | | -```bash |
60 | | -hugo server |
61 | | -``` |
62 | | - |
63 | | -## Running a container locally |
64 | | - |
65 | | -You can run docsy-example inside a [Docker](https://docs.docker.com/) |
66 | | -container, the container runs with a volume bound to the `docsy-example` |
67 | | -folder. This approach doesn't require you to install any dependencies other |
68 | | -than [Docker Desktop](https://www.docker.com/products/docker-desktop) on |
69 | | -Windows and Mac, and [Docker Compose](https://docs.docker.com/compose/install/) |
70 | | -on Linux. |
71 | | - |
72 | | -1. Build the docker image |
73 | | - |
74 | | - ```bash |
75 | | - docker-compose build |
76 | | - ``` |
77 | | - |
78 | | -1. Run the built image |
79 | | - |
80 | | - ```bash |
81 | | - docker-compose up |
82 | | - ``` |
83 | | - |
84 | | - > NOTE: You can run both commands at once with `docker-compose up --build`. |
85 | | -
|
86 | | -1. Verify that the service is working. |
87 | | - |
88 | | - Open your web browser and type `http://localhost:1313` in your navigation bar, |
89 | | - This opens a local instance of the docsy-example homepage. You can now make |
90 | | - changes to the docsy example and those changes will immediately show up in your |
91 | | - browser after you save. |
92 | | - |
93 | | -### Cleanup |
94 | | - |
95 | | -To stop Docker Compose, on your terminal window, press **Ctrl + C**. |
96 | | - |
97 | | -To remove the produced images run: |
98 | | - |
99 | | -```bash |
100 | | -docker-compose rm |
101 | | -``` |
102 | | -For more information see the [Docker Compose documentation][]. |
103 | | - |
104 | | -## Using a local Docsy clone |
105 | | - |
106 | | -Make sure your installed go version is `1.18` or higher. |
107 | | - |
108 | | -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. |
109 | | - |
110 | | -```shell |
111 | | -cd root-of-your-site |
112 | | -git clone --branch v0.12.0 https://github.com/google/docsy.git ../docsy |
113 | | -``` |
114 | | - |
115 | | -Now run: |
116 | | - |
117 | | -```shell |
118 | | -HUGO_MODULE_WORKSPACE=docsy.work hugo server --ignoreVendorPaths "**" |
119 | | -``` |
120 | | - |
121 | | -or, when using npm, prepend `local` to the script you want to invoke, e.g.: |
122 | | - |
123 | | -```shell |
124 | | -npm run local serve |
125 | | -``` |
126 | | - |
127 | | -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. |
128 | | - |
129 | | -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`: |
130 | | - |
131 | | -```toml |
132 | | -[module] |
133 | | - workspace = "docsy.work" |
134 | | -``` |
135 | | - |
136 | | -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. |
137 | | - |
138 | | -## Troubleshooting |
139 | | - |
140 | | -As you run the website locally, you may run into the following error: |
141 | | - |
142 | | -```console |
143 | | -$ hugo server |
144 | | -WARN 2023/06/27 16:59:06 Module "project" is not compatible with this Hugo version; run "hugo mod graph" for more information. |
145 | | -Start building sites … |
146 | | -hugo v0.101.0-466fa43c16709b4483689930a4f9ac8add5c9f66+extended windows/amd64 BuildDate=2022-06-16T07:09:16Z VendorInfo=gohugoio |
147 | | -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 |
148 | | -Built in 27 ms |
149 | | -``` |
150 | | - |
151 | | -This error occurs if you are running an outdated version of Hugo. As of docsy theme version `v0.12.0`, hugo version `0.146.0` or higher is required. |
152 | | -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. |
153 | | - |
154 | | -Or you may be confronted with the following error: |
155 | | - |
156 | | -```console |
157 | | -$ hugo server |
158 | | - |
159 | | -INFO 2021/01/21 21:07:55 Using config file: |
160 | | -Building sites … INFO 2021/01/21 21:07:55 syncing static files to / |
161 | | -Built in 288 ms |
162 | | -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 |
163 | | -``` |
164 | | - |
165 | | -This error occurs if you have not installed the extended version of Hugo. |
166 | | -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. |
167 | | - |
168 | | -Or you may encounter the following error: |
169 | | - |
170 | | -```console |
171 | | -$ hugo server |
172 | | - |
173 | | -Error: failed to download modules: binary with name "go" not found |
174 | | -``` |
175 | | - |
176 | | -This error occurs if the `go` programming language is not available on your system. |
177 | | -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`. |
178 | | - |
179 | | - |
180 | | -[alternate dashboard]: https://app.netlify.com/sites/goldydocs/deploys |
181 | | -[deploys]: https://app.netlify.com/sites/docsy-example/deploys |
182 | | -[Docsy user guide]: https://docsy.dev/docs |
183 | | -[Docsy]: https://github.com/google/docsy |
184 | | -[example.docsy.dev]: https://example.docsy.dev |
185 | | -[Hugo theme module]: https://gohugo.io/hugo-modules/use-modules/#use-a-module-for-a-theme |
186 | | -[Netlify]: https://netlify.com |
187 | | -[Docker Compose documentation]: https://docs.docker.com/compose/gettingstarted/ |
| 5 | +The website uses [Google Docsy](https://www.docsy.dev/) and the [Hugo framework](https://gohugo.io/). |
0 commit comments