https://github.com/raku/doc-website
Tooling to build/run the documentation website
https://github.com/raku/doc-website
Last synced: 3 months ago
JSON representation
Tooling to build/run the documentation website
- Host: GitHub
- URL: https://github.com/raku/doc-website
- Owner: Raku
- License: artistic-2.0
- Created: 2023-01-20T15:07:46.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-08-19T18:59:19.000Z (9 months ago)
- Last Synced: 2024-09-22T21:02:21.537Z (8 months ago)
- Language: CSS
- Size: 2.69 MB
- Stars: 7
- Watchers: 10
- Forks: 10
- Open Issues: 30
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Raku Documentation
>The Collection files for the Raku Documentation site.
## Table of Contents
[Installation](#installation)
[Building the documentation locally](#building-the-documentation-locally)
[Options for build-site](#options-for-build-site)
[Directory naming](#directory-naming)
[Deprecated URLs](#deprecated-urls)
[Plugins and Templates](#plugins-and-templates)
[Working on Collection plugins](#working-on-collection-plugins)
[Deployment of website](#deployment-of-website)
[Updates to the README](#updates-to-the-readme)
----
(The README.md version is generated from `repo_docs/README.rakudoc`)
# Installation
These instructions assume a Unix-like system.
This repo can be cloned and the main dependencies can be installed with
```
zef install . --deps-only
```
in the cloned directory. There are a couple of C libraries that may need to be installed as well, such as OpenSSL and LibArchive (make sure to install the ``-dev`` versions).
Cro is needed for serving the rendered files locally. You may wish to install it separately.
We have reports of some users missing a curl dependency despite having curl available from the command line. If this happens to you, please add `--exclude="curl"` to the zef command.
If you are missing `dot`, install the graphviz package for your OS.
# Building the documentation locally
Generic build steps:
* clone this repo to `raku-doc-website/`
* No need to clone the Raku documentation sources at `github.com/raku/doc/doc` to `local_raku_docs/doc/` as this is done automatically by the final step. However, if you already have a local `raku/doc` repo, then change the relevant key in `config.raku`. It should be intuitive what is required.
* Note also the `'_'` character in the default directory name. This is important for Collection if the document sources are under the `raku-doc-website` because Collection treats directories without `'_'` as `mode` directories.
* assume the rendered html will be built in `rendered_html`
All these names can be changed by changing the relevant parts of the config.raku file
Now run
```
bin_files/build-site
```
If Cro and Cro::HTTP have been installed, then `build-site` will automatically launch a Cro app and the whole website will be served on `localhost:30000`.
# Options for `build-site`
There are many options for build-site, which is a thin wrapper around the `collect` sub in `Collection`.
However, you can run
```
bin_files/build-site --help
```
or
```
bin_files/build-site --more-help
```
for a quick overview.
# Directory naming
As mentioned in the items above, Collection expects a sub-directory that does not include a `'_'` in its name to be a 'Mode'.
For this reason, documentation sources for this repo are in `repo_docs` and the binaries are in `bin_files`.
This may eventually prove unnecessary, but it is a reasonable convention is kept for the time being.
Further, in the future, another Mode may be useful in this repository in due course that generates an epub output.
# Deprecated URLs
Occasionally, file names change. This would cause a 404 error if an external webpage, e.g. someone's blog, has a link to a changed file name. To overcome this, a mapping file `deprecated-urls` is kept in `Website/plugins/raku-doc-setup`. The plugin adds this file to ``rendered_html/assets/``, and the Caddy system rewrites routes from the deprecated name to the working alternative.
# Plugins and Templates
Collection is designed to handle multiple Modes, and for plugins to be contributed in a similar way to Raku Modules. However, for the Raku documentation system, it seems pragmatic at the start for the plugins to be tailored specifically for this site.
Consequently, the plugins are directly copied into the OgdenWebb directory, rather than using Collection's `refresh` functionality. This comment may seem odd but I include it to preclude questions that will arise when reading the documentation for `Collection`.
The Templates were originally developed to mimic **Moritz Lenz's** Raku site (the one we are used to). Relevant template keys are modified in the `ogdenwebb` plugin. I would expect this to change over time, and for the default templates to change to the OgdenWebb templates. But I would suggest this is done incrementally.
# Working on Collection plugins
Collection uses plugins - they can be found under the directory `Website/plugins/ ` - which contain both callables that set up templates, associate CSS (defined using SCSS) with classes etc, and manipulate data.
Whilst the best way to work on the plugins is, as described below, to use the dedicated plugins distribution, it increases the learning curve and also means that there is an extra step in directly importing Collection plugins to the Raku Documentation repo (as mentioned above, the 'refresh' functionality of Collection is not used here).
However, to make development here easier, there are three utilities which directly affect this distribution:
* `update-css` which is a Bash file and takes the name of a plugin as its argument.
* `bin_files/test-all-plugins` This runs all the test files in all the plugins
* `bin_files/build-site` By default this will
* refresh the documents from the contents repository at github/raku/docs
* cache any changes to the source documents
* render all the source documents
However, if a change to a plugin has been made and it can be seen with only one or two source files, then it is quicker to use the `build-site` option `with-only`, e.g.
```
bin_files/build-site --with-only='language.rakudoc operators'
```
There is a file in `Website/structure-sources/language.rakudoc` and a file in the doc sources called `doc/language/operators.pod6`. Any element in the space delimited list following `--with-only` that matches a source file name will be rendered.
A better way, though, to tweak or add new plugins and see how they affect the website, is to install the distribution `raku-collection-plugin-development`.
# Deployment of website
The main branch is deployed to `docs-dev.raku.org` every two hours. Look there to see your changes after they're merged.
The production version of the website is `docs.raku.org`. Administrators update it manually, after verifying things look good on dev.
# Updates to the README
The markdown in the root of the project can be updated with this command
```
raku --doc=MarkDown2 repo_docs/README.rakudoc > README.md
```
----
Rendered from at 2024-11-12T02:43:57Z