|
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) and |
| 4 | +[@oleksandr-pavlyk](https://github.com/oleksandr-pavlyk) for [SciPy 2024](https://scipy2024.scipy.org). |
7 | 5 |
|
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 | +The website uses [Google Docsy](https://www.docsy.dev/) and the [Hugo framework](https://gohugo.io/). |
0 commit comments