As you saw in our introduction, Docsy is a Hugo theme, which means that if you want to use Docsy, you need to set up your website source so that the Hugo static site generator can find and use the Docsy theme files when building your site. The simplest way to do this is to copy and edit our example site, though we also provide instructions for adding the Docsy theme manually to new or existing sites.
If you want to build and test your site locally you also need to be able to run Hugo itself, either by installing it and any other required dependencies, or by using our provided Docker container.
This page describes Docsy’s installation options and helps you choose the appropriate setup guide to get started.
Installation options
Hugo offers multiple options for using themes, all of which are supported by Docsy.
Adding the theme as a Hugo Module: Hugo Modules are the simplest and latest way to use Hugo themes. Hugo uses the modules mechanism to pull in the theme files from the main Docsy repo at your chosen revision, and it’s easy to keep the theme up to date in your site. Our example site uses Docsy as a Hugo Module.
Adding the theme as a Git submodule: Adding the theme as a Git submodule also lets Hugo use the theme files from their own repo, though is more complicated to maintain than the Hugo modules approach. This is the approach used in older versions of the Docsy example site and is still supported.
Cloning the theme files: If you don’t want Hugo to have to get the theme files from an external repo (for example, if you want to customize and maintain your own copy of the theme directly, or your deployment choice requires you to include a copy of the theme in your repository), you can clone the files directly into your site source.
Migration and backward compatibility
If you have an existing site that uses Docsy as a Git submodule, and you would like to update it to use Hugo Modules, follow our migration guide. If you’re not ready to migrate yet, don’t worry! Your site will continue to work as usual.
Setup guides
Follow the setup guide for your chosen approach. If you’re new to Docsy and not sure which guide to follow, we recommend following the Use Docsy as a Hugo Module guide as a simple and easily maintained option.
1 - Quatm的下载与安装
Learn how to get started with Docsy by using the theme as a Hugo Module.
Hugo modules are the simplest and latest way to use Hugo themes like Docsy when building a website. Hugo uses the modules mechanism to pull in the theme files from the main Docsy repo at your chosen revision, and it’s easy to keep the theme up to date in your site. Our example site uses Docsy as a Hugo module.
To find out about other setup approaches, see our Get started overview. If you want to migrate an existing Docsy site to use Hugo Modules, see our migration guide.
Setup options with Hugo Modules
To use Docsy as a Hugo Module, you have a couple of options:
Copy and edit the source for the Docsy example site. This approach gives you a skeleton structure for your site, with top-level and documentation sections and templates that you can modify as necessary. The example site uses Docsy as a Hugo Module.
Build your own site using the Docsy theme. Specify the Docsy theme like any other Hugo theme when creating or updating your site. With this option, you’ll get Docsy look and feel, navigation, and other features, but you’ll need to specify your own site structure.
If you’re a beginner, we recommend that you get started by copying our example site. If you’re already familiar with Hugo or want a very different site structure, you can follow our guide to start a site from scratch, which gives you maximum flexibility at the cost of higher implementation effort. In both cases you need to follow our prerequisites guide to make sure that you have installed Hugo and all necessary dependencies.
1.1 - Before you begin
Prerequisites for building a site with Docsy as a Hugo Module.
This page describes the prerequisites for building a site that uses Docsy as a Hugo Module.
Install Hugo
You need a recent extended version (version 0.110.0 or later) of Hugo to do local builds and previews of sites (like this one) that use Docsy. If you install from the release page, make sure to get the extended Hugo version, which supports SCSS; you may need to scroll down the list of releases to see it.
For comprehensive Hugo documentation, see gohugo.io.
If you’ve already installed Hugo, check your version:
hugo version
If the result is v0.109.0 or earlier, or if you don’t see Extended, you’ll need to install the latest version. You can see a complete list of Linux installation options in Install Hugo. The following shows you how to install Hugo from the release page:
You can install Hugo as an npm module using hugo-bin. This adds hugo-bin to your node_modules folder and adds the dependency to your package.json file. To install the extended version of Hugo:
Hugo’s commands for module management require that the Go programming language is installed on your system. Check whether go is already installed:
$ go version
go version go1.21.6
Ensure that you are using version 1.12 or higher.
If the go language is not installed on your system yet or if you need to upgrade, go to the download area of the Go website, choose the installer for your system architecture and execute it. Afterwards, check for a successful installation.
Install Git VCS client
Hugo’s commands for module management require that the git client is installed on your system. Check whether git is already present in your system:
$ git version
git version 2.43.0
If no git client is installed on your system yet, go to the Git website, download the installer for your system architecture and execute it. Afterwards, check for a successful installation.
Install PostCSS
To build or update your site’s CSS resources, you also need PostCSS to create the final assets. If you need to install it, you must have a recent version of NodeJS installed on your machine so you can use npm, the Node package manager. By default npm installs tools under the directory where you run npm install:
Note that versions of PostCSS later than 5.0.1 will not load autoprefixer if installed globally, you must use a local install.
Install/Upgrade Node.js
To ensure you can properly build your site beyond executing hugo server, you must have the latest long term support (LTS) Version of Node.js. If you do not have the latest LTS version, you may see the one of following errors:
Error: Error building site: POSTCSS: failed to transform "scss/main.css" (text/css): Unexpected identifier
#OR
/home/user/repos/my-new-site/themes/docsy/node_modules/hugo-extended/postinstall.js:1
import install from "./lib/install.js";
^^^^^^^
SyntaxError: Unexpected identifier
at Module._compile (internal/modules/cjs/loader.js:723:23)
at Object.Module._extensions..js (internal/modules/cjs/loader.js:789:10)
at Module.load (internal/modules/cjs/loader.js:653:32)
at tryModuleLoad (internal/modules/cjs/loader.js:593:12)
at Function.Module._load (internal/modules/cjs/loader.js:585:3)
at Function.Module.runMain (internal/modules/cjs/loader.js:831:12)
at startup (internal/bootstrap/node.js:283:19)
at bootstrapNodeJSCore (internal/bootstrap/node.js:623:3)
You can check your current Node.js version by running node -v. If you need to install a new version, see the following instructions:
1.2 - Create a new site: start with a prepopulated site
Create a new Hugo site by using a clone of the Docsy example site as your starting point.
The simplest way to create a new Docsy site is to use the source of the Docsy example site as starting point. This approach gives you a skeleton structure for your site, with top-level and documentation sections and templates that you can modify as necessary. The example site automatically pulls in the Docsy theme as a Hugo Module, so it’s easy to keep up to date.
If you prefer to create a site from scratch, follow the instructions in Start a site from scratch.
TL;DR: Setup for the impatient expert
At your Unix shell or Windows command line, run the following command:
git clone --depth 1 --branch v0.10.0 https://github.com/quatm/quatm-example.git my-new-site
cd my-new-site
hugo server
The Example Site gives you a good starting point for building your docs site and is
pre-configured to automatically pull in the Docsy theme as a Hugo Module.
There are two different routes to get a local clone of the example site:
If you want to create a local copy only, choose option 1.
If you have a GitHub account and want to create a GitHub repo for your site go for option 2.
Option 1: Using the command line (local copy only)
If you want to use a remote repository other than GitHub (such as GitLab, BitBucket, AWS CodeCommit, Gitea) or if you don’t want a remote repo at all, simply make a local working copy of the example site directly using git clone. As last parameter, give your chosen local repo name (here: my-new-site):
Use the dropdown for switching branches/tags to change to the latest released tag v0.10.0.
Click the button Use this template and select the option Create a new repository from the dropdown.
Chose a name for your new repository (e.g. my-new-site) and type it in the Repository name field. You can also add an optional Description.
Click Create repository from template to create your new repository. Congratulations, you just created your remote Github clone which now serves as starting point for your own site!
Make a local copy of your newly created GitHub repository by using git clone, giving your repo’s web URL as last parameter.
Depending on your environment you may need to tweak the module top level settings inside your hugo.toml slightly, for example by adding a proxy to use when downloading remote modules.
You can find details of what these configuration settings do in the Hugo modules documentation.
Now you can make local edits and test your copied site locally with Hugo.
Preview your site
To build and preview your site locally, switch to the root of your cloned project and use hugo’s server command:
cd my-new-site
hugo server
Preview your site in your browser at: http://localhost:1313.
Thanks to Hugo’s live preview, you can immediately see the effect of changes that you are making to the source files of your local repo.
Use Ctrl + c to stop the Hugo server whenever you like.
See the known issues on MacOS.
1.3 - Create a new site: Start a new site from scratch
Create a new Hugo site from scratch with Docsy as a Hugo Module
The simplest approach to creating a Docsy site is copying our example site. However, if you’re an experienced Hugo user or the site structure of our example site doesn’t meet your needs, you may prefer to create a new site from scratch. With this option, you’ll get Docsy look and feel, navigation, and other features, but you’ll need to specify your own site structure.
These instructions give you a minimum file structure for your site project only, so that you build and extend your actual site step by step. The first step is adding the Docsy theme as a Hugo Module to your site. If needed, you can easily update the module to the latest revision from the Docsy GitHub repo.
TL;DR: Setup for the impatient expert
At your command prompt, run the following:
hugo new site my-new-site
cd my-new-site
hugo mod init github.com/me/my-new-site
hugo mod get github.com/google/docsy@v0.10.0
cat >> hugo.toml <<EOL
[module]
proxy = "direct"
[[module.imports]]
path = "github.com/google/docsy"
EOLhugo server
hugo new site my-new-site
cd my-new-site
hugo mod init github.com/me/my-new-site
hugo mod get github.com/google/docsy@v0.10.0
(echo [module]^
proxy = "direct"^
[[module.imports]]^
path = "github.com/google/docsy")>> hugo.toml
hugo server
Specifying the Docsy theme as Hugo Module for your minimal site gives you all the theme-y goodness, but you’ll need to specify your own site structure.
Create your new skeleton project
To create a new Hugo site project and then add the Docs theme as a submodule, run the following commands from your project’s root directory.
hugo new site my-new-site
cd my-new-site
This will create a minimal site structure, containing the folders archetypes, content, data, layouts, static, and themes and a configuration file (default: hugo.toml).
Tip
In Hugo 0.110.0 the default config base filename was changed to hugo.toml.
If you are using hugo 0.110 or above, consider renaming your config.toml to hugo.toml!
Import the Docsy theme module as a dependency of your site
Only sites that are Hugo Modules themselves can import other modules. To turn your site into a Hugo Module, run the following commands in your newly created site directory:
hugo mod init github.com/me/my-new-site
This creates two new files, go.mod for the module definitions and go.sum which holds the checksums for module verification.
Next declare the Docsy theme module as a dependency for your site.
hugo mod get github.com/google/docsy@v0.10.0
This command adds the docsy theme module to your definition file go.mod.
Add theme module configuration settings
Add the settings in the following snippet at the end of your site’s configuration file (default: hugo.toml) and save the file.
[module]proxy="direct"# uncomment line below for temporary local development of module# replacements = "github.com/google/docsy -> ../../docsy"[module.hugoVersion]extended=truemin="0.73.0"[[module.imports]]path="github.com/google/docsy"disable=false
You can find details of what these configuration settings do in the Hugo modules documentation.
Depending on your environment you may need to tweak them slightly, for example by adding a proxy to use when downloading remote modules.
Preview your site
To build and preview your site locally:
hugo server
By default, your site will be available at http://localhost:1313. When encountering problems, have a look at the known issues on MacOS.
You may get Hugo errors for missing parameters and values when you try to build your site. This is usually because you’re missing default values for some configuration settings that Docsy uses - once you add them your site should build correctly. You can find out how to add configuration in Basic site configuration - we recommend copying the example site configuration even if you’re creating a site from scratch as it provides defaults for many required configuration parameters.
Create a new Docsy site with Docsy using Git or NPM
If you don’t want to use
Docsy as a Hugo Module (for example if you
do not want to install Go) but still don’t want to copy the theme files into
your own repo, you can use Docsy as a
Git submodule. Using
submodules also lets Hugo use the theme files from Docsy repo, though is more
complicated to maintain than the Hugo Modules approach. This is the approach
used in older versions of the Docsy example site, and is still supported. If you
are using Docsy as a submodule but would like to migrate to Hugo Modules, see
our migration guide.
Alternatively if you don’t want Hugo to have to get the theme files from an
external repo (for example, if you want to customize and maintain your own copy
of the theme directly, or your deployment choice requires you to include a copy
of the theme in your repository), you can clone the files directly into your
site source.
This guide provides instructions for all of these options, along with common
prerequisites.
Prerequisites
Install Hugo
You need a
recent extended version (we
recommend version 0.73.0 or later) of Hugo to do local
builds and previews of sites (like this one) that use Docsy. If you install from
the release page, make sure to get the extended Hugo version, which supports
SCSS; you
may need to scroll down the list of releases to see it.
For comprehensive Hugo documentation, see gohugo.io.
If you’ve already installed Hugo, check your version:
hugo version
If the result is v0.73 or earlier, or if you don’t see Extended, you’ll need
to install the latest version. You can see a complete list of Linux installation
options in Install Hugo.
The following shows you how to install Hugo from the release page:
You can install Hugo as an NPM module using
hugo-extended. To install the
extended version of Hugo:
npm install hugo-extended --save-dev
Node: Get the latest LTS release
If you have Node installed already, check your version of Node. For example:
node -v
Install or upgrade your version of Node to the active LTS release. We
recommend using nvm to manage your Node installation (Linux command
shown):
nvm install --lts
Install PostCSS
To build or update your site’s CSS resources, you’ll also need
PostCSS. Install it using the Node package manager,
npm.
IMPORTANT: Check your Node version
The PostCSS package installed by some older versions of Node is incompatible
with Docsy. Check your version of Node against the active LTS release
and upgrade, if necessary. For details, see Node: Get the latest LTS
release.
From your project root, run this command:
npm install --save-dev autoprefixer postcss-cli
Option 1: Docsy as a Git submodule
For a new site
To create a new site and add the Docsy theme as a Git submodule, run the
following commands:
In Hugo 0.110.0 the default config base filename was changed to hugo.toml.
If you are using hugo 0.110 or above, consider renaming your config.toml to hugo.toml!
(Optional but recommended) To avoid having to repeat the previous step every
time you update Docsy, consider adding NPM scripts like the following to
your project’s package.json file:
{"...":"...","scripts":{"get:submodule":"git submodule update --init --depth 1","_prepare:docsy":"cd themes/docsy && npm install","prepare":"npm run get:submodule && npm run _prepare:docsy","...":"..."},"...":"..."}
Every time you run npm install from your project root, the prepare
script will fetch the latest version of Docsy and its dependencies.
From this point on, build and serve your site using the usual Hugo commands, for
example:
hugo serve
Option 2: Clone the Docsy theme
If you don’t want to use a submodules (for example, if you want to customize and
maintain your own copy of the theme directly, or your deployment choice requires
you to include a copy of the theme in your repository), you can clone the theme
into your project’s themes subdirectory.
To clone Docsy at v0.10.0 into your project’s theme folder, run
the following commands from your project’s root directory:
cd themes
git clone -b v0.10.0 https://github.com/quatm/quatm
cd docsy
npm install
To work from the development version of Docsy (not recommended unless, for
example, you plan to upstream changes to Docsy), omit the -b v0.10.0 argument from the clone command above.
Then consider setting up an NPM prepare script, as documented in Option 1.
Build or serve your new site using the usual Hugo commands, specifying the
path to the Docsy theme files. For example, build your site as follows:
$ hugo --themesDir node_modules
Start building sites …
...
Total in 1890 ms
You can drop the --themesDir ... flag by adding the themes directory to
your site’s configuration file:
echo'themesDir = "node_modules"' >> hugo.toml
As an alternative to specifying a themesDir, on some platforms, you can
instead create a symbolic link to the Docsy theme directory as follows (Linux
commands shown, executed from the site root folder):
You may get Hugo errors for missing parameters and values when you try to build
your site. This is usually because you’re missing default values for some
configuration settings that Docsy uses - once you add them your site should
build correctly. You can find out how to add configuration in
Basic site configuration - we
recommend copying the example site configuration even if you’re creating a site
from scratch as it provides defaults for many required configuration parameters.
This package provides control over your experiments. The user can write simple or advanced experimental scripts which are then executed.
Tutorial
Getting started:
To define an experiment you need to create a class that inherits from Experiment and has at least the functions build and run defined. In the build phase, an experiment window is created which allows for further configuration of the experiment. The run phase is executed when you click on ‘run’ in the window. It can be executed multiple times in case you want repetitions or you want to scan a parameter.
Simple example:
classmy_experiment(Experiment):defbuild():# this function is executed once when the file is loaded.# you want to use the dac MyDAC you configured in device.dbself.setattr_device("Mydac")# -0.1600# define additional variablesself.setattr_argument("targetvoltage",NumberValue(ndecimals=2,step=0.01,value=4.00))defrun():# this function is executed for each run of the experimentself.Mydac=1# set the dac to 1Vdelay(1)# delay 1 secondself.Mydac=self.targetvoltage# set the DAC to a user-defined target voltage
In this simple example, you declare that you need access to the Mydac DAC. Mydac must be a valid entry in your device.db (see below how to configure your system). All setattr_... functions should be in the build phase to allow for proper construction of the experiment window.
The additional variable defined is targetvoltage. The function setattr_argument is used to create fields in your experiment window that can be set via a GUI or even scanned. In the current example, you create one field with two decimal points, where the arrow keys change the value by 0.01 and the default value when the window is opened is 4.
In the run() section the output is set to 1V. Then you wait for one second and set the value to the user-defined value. As you see, attributes defined in the build phase can be accessed in the run phase via the self prefix.
Basic Adwin Configuration
The central configuration file device_db.py is located in the directory quatm/configuration. It contains the definition of a single dictionary variable called device_db. Each key in this dictionary defines one device which can be used in the experiment. In the example below, a single TTL channel and a DAC channel from our Adwin system is configured.
As you can see there are two entries. The first entry needs to be called adwin and is a local driver. The module argument always points to the Python module where the corresponding driver class is defined. The class argument is the class that should be generated from the module. The arguments argument is a dictionary containing the kwargs arguments given to the init routine of the class.
The second entry configures one TTL channel of the Adwin system. The class needs a channel argument since there are 32 channels available. In order to use the ttl module, the adwin entry needs to be defined.
The third entry defines a DAC channel. For DAC channels, additional arguments could be given.
Embedding your own drivers
Suppose you have written a driver module called evalcontrol which contains a class definition called AD9959. Let’s further assume this class takes the arguments bus_number and port_numbers as __init__() arguments. Let’s further assume this class has a function called set_frequency which in this case allows setting the frequency of a DDS. Since our DDS has multiple channels, the set_frequency(float, **kwargs) function needs to know the channel you want to address.
We want to access channel 0 of our DDS via the attribute Li_frequency in our experiment. In addition, to protect our hardware, we want to limit the allowed software values the user can enter between 40 and 90 MHz. For this case scenario, the device_db dictionary should contain the following entries:
The first entry generates an instance of the class defined in your driver module using the proper init arguments. Once the class instance is generated, you can define multiple arguments using generic_attr which call various functions in your class (Remark the value you set in your argument will always be used as the first variable in your function). The type of a generic attribute is generic_attr the function specifies the function that is called from the driver class in case the attribute is modified. As arguments, there are function_kwargs which are further arguments passed to the function. minval and maxval provide software limits for the argument. multiplier is used for the display of the arguments. When writing experiment scripts SI units have to be used. Therefore valid values would be between 4E7 and 9E7 or 40MHz to 90MHz. In the GUI, the multiplier and display_unit is used. The step argument controls the step size used in the GUI. Pressing the arrow key will change the value by 0.1 MHz.
In your experiment, you can access your driver now like this:
classmy_experiment(Experiment):defbuild():self.setattr_device("Li_frequency")self.setattr_device("lithium_dds_0")# you need this entry to create the driver class instancedefrun():self.Li_frequency=66E6# set the DDS to 66MHzdelay(1)# delay 1 secondself.Li_frequency=50E6# set DDS to 50MHz
Using gauge files:
BaLiC DAC channels support the use of gauge files. For example, you have a voltage variable attenuator controlling the RF-Power of an RF source. However, this attenuator has a nonlinear curve. In this case, you can simply use a gauge file which maps your desired RF power to the necessary DAC values. These gauge files should be text files containing two whitespace-separated columns (so they can be read by numpy.loadtxt).
In the first column, there are the DAC values. In the second column, there is the RF power. The two columns should be such that the relation is strictly monotonic. To set up your gauge files, it is a good practice to use SI basis units e.g. rather write 1.12E-7 W than 11.2 µW.
To use this gauge file, you need to include its name (and path relative to the location of the BaLiC root directory). In the example, the gauge file RF-gauge2.dat is in the configuration directory.
Site-wide configuration details and parameters are defined in your project’s configuration file (hugo.toml or config.toml). These include your chosen Hugo theme (Docsy, of course!), project name, community links, Google Analytics configuration, and Markdown parser parameters. See the examples with comments in hugo.toml in the example project for how to add this information. We recommend copying this hugo.toml and editing it even if you’re just using the theme and not copying the entire Docsy example site, as it includes default values for many parameters that you need to set for your site to build correctly.
You may want to remove or customize some defaults of the copied hugo.toml file straight away:
Internationalization
The copied hugo.toml file defines content in English, Norwegian and Farsi. You can find out more about how Docsy supports multi-language content in Multi-language support.
If you don’t intend to translate your site, you can remove the language switcher by removing the following lines from hugo.toml:
[languages.no]languageName="Norsk"contentDir="content/no"[languages.no.params]title="Goldydocs"description="Docsy er operativsystem for skyen"time_format_default="02.01.2006"time_format_blog="02.01.2006"[languages.fa]languageName="فارسی"contentDir="content/fa"[languages.fa.params]title="اسناد گلدی"description="یک نمونه برای پوسته داکسی"time_format_default="2006.01.02"time_format_blog="2006.01.02"
Search
By default, the Docsy example site uses its own Google Custom Search Engine. To disable this site search, delete or comment out the following lines:
# Google Custom Search Engine ID. Remove or comment out to disable search.
gcs_engine_id = "..."
Errors: too many open files or fatal error: pipe failed
By default, MacOS permits a small number of open File Descriptors. For larger sites, or when you’re simultaneously running multiple applications,
you might receive one of the following errors when you run hugo server to preview your site locally:
POSTCSS v7 and earlier:
ERROR 2020/04/14 12:37:16 Error: listen tcp 127.0.0.1:1313: socket: too many open files
POSTCSS v8 and later:
fatal error: pipe failed
Workaround
To temporarily allow more open files:
View your current settings by running:
sudo launchctl limit maxfiles
Increase the limit to 65535 files by running the following commands. If your site has fewer files, you can set choose to set lower soft (65535) and
hard (200000) limits.
If you’re using WSL, ensure that you’re running hugo on a Linux mount of the filesystem, rather than a Windows one, otherwise you may get unexpected errors.