From 98ed75b1be4d50547d065659e201618d950f3db2 Mon Sep 17 00:00:00 2001 From: Nicolas Paul Date: Wed, 4 Oct 2023 09:03:20 +0200 Subject: Make all pages Markdown documents We do not use MDX features --- doc/pages/guide.md | 261 +++++++++++++++++++++++++++++++++++++++++++++++ doc/pages/guide.mdx | 261 ----------------------------------------------- doc/pages/index.md | 130 +++++++++++++++++++++++ doc/pages/index.mdx | 129 ----------------------- doc/pages/references.md | 186 +++++++++++++++++++++++++++++++++ doc/pages/references.mdx | 186 --------------------------------- 6 files changed, 577 insertions(+), 576 deletions(-) create mode 100644 doc/pages/guide.md delete mode 100644 doc/pages/guide.mdx create mode 100644 doc/pages/index.md delete mode 100644 doc/pages/index.mdx create mode 100644 doc/pages/references.md delete mode 100644 doc/pages/references.mdx diff --git a/doc/pages/guide.md b/doc/pages/guide.md new file mode 100644 index 0000000..ed098e4 --- /dev/null +++ b/doc/pages/guide.md @@ -0,0 +1,261 @@ +--- +# Copyright Nicolas (2023) +# +# * Nicolas Paul +# +# This software is a computer program whose purpose is to allow the hosting +# and sharing of Go modules using a personal domain. +# +# This software is governed by the CeCILL license under French law and +# abiding by the rules of distribution of free software. You can use, +# modify and/ or redistribute the software under the terms of the CeCILL +# license as circulated by CEA, CNRS and INRIA at the following URL +# "http://www.cecill.info". +# +# As a counterpart to the access to the source code and rights to copy, +# modify and redistribute granted by the license, users are provided only +# with a limited warranty and the software's author, the holder of the +# economic rights, and the successive licensors have only limited +# liability. +# +# In this respect, the user's attention is drawn to the risks associated +# with loading, using, modifying and/or developing or reproducing the +# software by the user in light of its specific status of free software, +# that may mean that it is complicated to manipulate, and that also +# therefore means that it is reserved for developers and experienced +# professionals having in-depth computer knowledge. Users are therefore +# encouraged to load and test the software's suitability as regards their +# requirements in conditions enabling the security of their systems and/or +# data to be ensured and, more generally, to use and operate it in the +# same conditions as regards security. +# +# The fact that you are presently reading this means that you have had +# knowledge of the CeCILL license and that you accept its terms. + +title: Example +description: | + An example and guide to setup and use SVGU to host a list of Go modules + on a given domain name. +--- + +# Example + +This document is a guide to setting up SVGU, configuring an index and hosting +it on a Web server. + +A production-ready example can be found for [go.nc0.fr](https://go.nc0.fr) +which works thanks to SVGU. The source repository is available on +[GitHub](https://github.com/nc0fr/gomods). + +## Getting Started + +To get started, you need to make sure you have [installed SVGU](./install.mdx). +Also, you will need a [text editing software](https://vim.org), +a web server (you can either host one yourself or use a service like +[Vercel](https://vercel.com) or +[Cloudflare Pages](https://pages.cloudflare.com), and a domain name with access +to your DNS. + +## Overview + +In this guide, we will use the `example.com` domain as our target. +We will assume the existence of three Go modules, `example.com/a` hosted on +GitHub (Git), `example.com/b` hosted on SourceHut (Mercurial), and +`example.com/c` hosted on a private server with Bazaar. + +Remember that Go supports [Bazaar][bzr], [Subversion][svn], [Git][git], +[Fossil][fossil], and [Mercurial][hg]. + +[bzr]: https://www.gnu.org/software/bazaar/ +[fossil]: https://www2.fossil-scm.org/home/doc/trunk/www/index.wiki +[git]: https://git-scm.com +[hg]: https://www.mercurial-scm.org +[svn]: https://subversion.apache.org + +## Writing the Configuration + +Let's create a file named `svgu.star` in a directory of your choice. +This file will serve as our index configuration. + +### Initialization + +Inside this file, we will initialize the index and register our three modules. +Let's start with the index: + +```python +# svgu.star + +index(domain="example.com") +``` + +The [`index()`](./references.mdx#index) is responsible for the initialization +of the index. It takes one argument (named `domain`) which corresponds to the +domain name the registry will be published at. +Since we have decided to use `example.com` in this guide, we set `domain` to +`example.com`. + +### Modules + +Next, we need to declare our three modules, `example.com/{a,b,c}`. +This can be achieved with the help of the +[`module()`](./references.mdx#module). + +```python +# svgu.star + +index(domain="example.com") + +# Module: example.com/a +# Hosted on GitHub with Git: https://github.com/example/a +# Share the "main" branch. +module( + name="a", + vcs="git", + repo="https://github.com/example/a", + dir="https://github.com/example/a/tree/main{/dir}", + file="https://github.com/example/a/blob/main{/dir}/{file}#{line}", +) + +# Module: example.com/b +# Hosted on Source Hut with Mercurial: https://hg.sr.ht/~example/b +# Share the "master" revision. +module( + name="b", + vcs="hg", + repo="https://hg.sr.ht/~example/b", + dir="https://hg.sr.ht/~example/b/browse{/dir}?rev=master", + file="https://hg.sr.ht/~example/b/browse{/dir}/{file}?rev=master#L{line}", +) + +# Module: example.com/c +# Private Bazaar repository. +# Share the "latest" revision of the "master" branch. +module( + name="c", + vcs="bzr", + repo="https://private.example.com/c", + dir="https://private.example.com/c/master{/dir}?rev=latest", + file="https://private.example.com/c/master{/dir}/{file}?rev=latest", +) +``` + +Here we can see our three Go modules declared successfully. + +### Helpers + +While you can write as many `module()` as required, there is a lot boilerplate +involved in declaring a module. Luckily, SVGU use the +[Starlark configuration language](./starlark.mdx) which helps with that. + +Indeed, imagine you need to declare multiple repositories, all hosted on your +public GitHub profile `example`. They all publish their `main` branch. + +You could write as many `module()` as needed, but this will be a long and +tedeous task, and it will be hard to maintain. +Instead, you can write a helper function: + +```python +# svgu.star + +index(domain="example.com") + +# To avoid mistyping the VCS, we can make a constant. +GIT = "git" + +def github(name): + """ + GitHub declares and registers a Go module hosted on GitHub + on the `example` account. + """ + + # The "%" operator is a shortcut for the ".format()" function. + # It allows variable substitution in strings. + repo = "https://github.com/example/%s" % name + dir = "%s/tree/main{/dir}" % repo + + module( + name=name, + vcs=GIT, + repo=repo, + dir=dir, + file="%s/blob/main{/dir}/{file}#{line}" % repo + ) + +# example.com/{d,e,f,g,h,i} all hosted on GitHub. +[ module(repo) in ("d", "e", "f", "g", "h", "i") ] +``` + +See how much easier it is to write and maintain! +Starlark is a programming language, you can use its properties to assist you +in your tasks, so make sure to use it. + +### Linting + +You can format and lint your configuration using the +[Buildifier](https://github.com/bazelbuild/buildtools). + +## Going to Production + +### Compiling + +Now that your configuration is ready, you may generate your index as a set +of HTML document. + +The `svgu` command-line tool accepts two parameters: + +- `-c=file` the configuration file to use, here it will be `svgu.star`; +- `-o=directory` the output directory. + +We want to generate our registry inside a directory called `out`. +Therefore, we can run: + +```bash +$ svgu -c=svgu.star -o=out +``` + +If everything runs well, you should end with a new directory `out/` containing +HTML documents: + +```bash +$ ls out +a.html b.html c.html index.html +``` + +### Deploying + +Now that you have everything ready inside your `out` directory, the last step +is to deploy the directory's content on the Web server of your choice. + +Make sure your Web server has URL rewriting enabled, such that the `.html` +extension is not required in the request URL (some services, including +[GitHub Pages](https://pages.github.io) and +[Cloudflare Pages](https://pages.cloudflare.com) have this enabled by default, +traditional servers may require configuration: +[Caddy](https://caddyserver.com/docs/caddyfile/directives/rewrite), +[NGINX](https://www.nginx.com/blog/creating-nginx-rewrite-rules)...). + +Finally, make sure you have correctly configured your DNS entries, and you +should quickly be able to import your Go modules using your domain name! + +## Additional Notes + +By default, the standard Go toolchain uses Google's Go module proxy to retrieve +modules. The proxy ensures the availablity of modules for all users by caching +Go modules. +However, due to the cache, you may experience delays and differences +between the latest pushed version and the imported one. These issues are +related to Google's proxy and are usually not an issue as the cache is often +updated in minutes. + +Additionnally, Google's proxy may cause a lot of requests on your Web server, +due to the *Go Team at Google*'s choice to update the cache quickly (and +therefore avoid stale data). +You may opt-out the proxy by +[contacting a maintainer](https://github.com/golang/go/issues/new). + +> Consider using a more powerful Web server or machine if needed, as the proxy +> is a valuable tool. + +In general, please read [proxy.golang.org](https://proxy.golang.org) for +everything related to the Go proxy and module index. + diff --git a/doc/pages/guide.mdx b/doc/pages/guide.mdx deleted file mode 100644 index ed098e4..0000000 --- a/doc/pages/guide.mdx +++ /dev/null @@ -1,261 +0,0 @@ ---- -# Copyright Nicolas (2023) -# -# * Nicolas Paul -# -# This software is a computer program whose purpose is to allow the hosting -# and sharing of Go modules using a personal domain. -# -# This software is governed by the CeCILL license under French law and -# abiding by the rules of distribution of free software. You can use, -# modify and/ or redistribute the software under the terms of the CeCILL -# license as circulated by CEA, CNRS and INRIA at the following URL -# "http://www.cecill.info". -# -# As a counterpart to the access to the source code and rights to copy, -# modify and redistribute granted by the license, users are provided only -# with a limited warranty and the software's author, the holder of the -# economic rights, and the successive licensors have only limited -# liability. -# -# In this respect, the user's attention is drawn to the risks associated -# with loading, using, modifying and/or developing or reproducing the -# software by the user in light of its specific status of free software, -# that may mean that it is complicated to manipulate, and that also -# therefore means that it is reserved for developers and experienced -# professionals having in-depth computer knowledge. Users are therefore -# encouraged to load and test the software's suitability as regards their -# requirements in conditions enabling the security of their systems and/or -# data to be ensured and, more generally, to use and operate it in the -# same conditions as regards security. -# -# The fact that you are presently reading this means that you have had -# knowledge of the CeCILL license and that you accept its terms. - -title: Example -description: | - An example and guide to setup and use SVGU to host a list of Go modules - on a given domain name. ---- - -# Example - -This document is a guide to setting up SVGU, configuring an index and hosting -it on a Web server. - -A production-ready example can be found for [go.nc0.fr](https://go.nc0.fr) -which works thanks to SVGU. The source repository is available on -[GitHub](https://github.com/nc0fr/gomods). - -## Getting Started - -To get started, you need to make sure you have [installed SVGU](./install.mdx). -Also, you will need a [text editing software](https://vim.org), -a web server (you can either host one yourself or use a service like -[Vercel](https://vercel.com) or -[Cloudflare Pages](https://pages.cloudflare.com), and a domain name with access -to your DNS. - -## Overview - -In this guide, we will use the `example.com` domain as our target. -We will assume the existence of three Go modules, `example.com/a` hosted on -GitHub (Git), `example.com/b` hosted on SourceHut (Mercurial), and -`example.com/c` hosted on a private server with Bazaar. - -Remember that Go supports [Bazaar][bzr], [Subversion][svn], [Git][git], -[Fossil][fossil], and [Mercurial][hg]. - -[bzr]: https://www.gnu.org/software/bazaar/ -[fossil]: https://www2.fossil-scm.org/home/doc/trunk/www/index.wiki -[git]: https://git-scm.com -[hg]: https://www.mercurial-scm.org -[svn]: https://subversion.apache.org - -## Writing the Configuration - -Let's create a file named `svgu.star` in a directory of your choice. -This file will serve as our index configuration. - -### Initialization - -Inside this file, we will initialize the index and register our three modules. -Let's start with the index: - -```python -# svgu.star - -index(domain="example.com") -``` - -The [`index()`](./references.mdx#index) is responsible for the initialization -of the index. It takes one argument (named `domain`) which corresponds to the -domain name the registry will be published at. -Since we have decided to use `example.com` in this guide, we set `domain` to -`example.com`. - -### Modules - -Next, we need to declare our three modules, `example.com/{a,b,c}`. -This can be achieved with the help of the -[`module()`](./references.mdx#module). - -```python -# svgu.star - -index(domain="example.com") - -# Module: example.com/a -# Hosted on GitHub with Git: https://github.com/example/a -# Share the "main" branch. -module( - name="a", - vcs="git", - repo="https://github.com/example/a", - dir="https://github.com/example/a/tree/main{/dir}", - file="https://github.com/example/a/blob/main{/dir}/{file}#{line}", -) - -# Module: example.com/b -# Hosted on Source Hut with Mercurial: https://hg.sr.ht/~example/b -# Share the "master" revision. -module( - name="b", - vcs="hg", - repo="https://hg.sr.ht/~example/b", - dir="https://hg.sr.ht/~example/b/browse{/dir}?rev=master", - file="https://hg.sr.ht/~example/b/browse{/dir}/{file}?rev=master#L{line}", -) - -# Module: example.com/c -# Private Bazaar repository. -# Share the "latest" revision of the "master" branch. -module( - name="c", - vcs="bzr", - repo="https://private.example.com/c", - dir="https://private.example.com/c/master{/dir}?rev=latest", - file="https://private.example.com/c/master{/dir}/{file}?rev=latest", -) -``` - -Here we can see our three Go modules declared successfully. - -### Helpers - -While you can write as many `module()` as required, there is a lot boilerplate -involved in declaring a module. Luckily, SVGU use the -[Starlark configuration language](./starlark.mdx) which helps with that. - -Indeed, imagine you need to declare multiple repositories, all hosted on your -public GitHub profile `example`. They all publish their `main` branch. - -You could write as many `module()` as needed, but this will be a long and -tedeous task, and it will be hard to maintain. -Instead, you can write a helper function: - -```python -# svgu.star - -index(domain="example.com") - -# To avoid mistyping the VCS, we can make a constant. -GIT = "git" - -def github(name): - """ - GitHub declares and registers a Go module hosted on GitHub - on the `example` account. - """ - - # The "%" operator is a shortcut for the ".format()" function. - # It allows variable substitution in strings. - repo = "https://github.com/example/%s" % name - dir = "%s/tree/main{/dir}" % repo - - module( - name=name, - vcs=GIT, - repo=repo, - dir=dir, - file="%s/blob/main{/dir}/{file}#{line}" % repo - ) - -# example.com/{d,e,f,g,h,i} all hosted on GitHub. -[ module(repo) in ("d", "e", "f", "g", "h", "i") ] -``` - -See how much easier it is to write and maintain! -Starlark is a programming language, you can use its properties to assist you -in your tasks, so make sure to use it. - -### Linting - -You can format and lint your configuration using the -[Buildifier](https://github.com/bazelbuild/buildtools). - -## Going to Production - -### Compiling - -Now that your configuration is ready, you may generate your index as a set -of HTML document. - -The `svgu` command-line tool accepts two parameters: - -- `-c=file` the configuration file to use, here it will be `svgu.star`; -- `-o=directory` the output directory. - -We want to generate our registry inside a directory called `out`. -Therefore, we can run: - -```bash -$ svgu -c=svgu.star -o=out -``` - -If everything runs well, you should end with a new directory `out/` containing -HTML documents: - -```bash -$ ls out -a.html b.html c.html index.html -``` - -### Deploying - -Now that you have everything ready inside your `out` directory, the last step -is to deploy the directory's content on the Web server of your choice. - -Make sure your Web server has URL rewriting enabled, such that the `.html` -extension is not required in the request URL (some services, including -[GitHub Pages](https://pages.github.io) and -[Cloudflare Pages](https://pages.cloudflare.com) have this enabled by default, -traditional servers may require configuration: -[Caddy](https://caddyserver.com/docs/caddyfile/directives/rewrite), -[NGINX](https://www.nginx.com/blog/creating-nginx-rewrite-rules)...). - -Finally, make sure you have correctly configured your DNS entries, and you -should quickly be able to import your Go modules using your domain name! - -## Additional Notes - -By default, the standard Go toolchain uses Google's Go module proxy to retrieve -modules. The proxy ensures the availablity of modules for all users by caching -Go modules. -However, due to the cache, you may experience delays and differences -between the latest pushed version and the imported one. These issues are -related to Google's proxy and are usually not an issue as the cache is often -updated in minutes. - -Additionnally, Google's proxy may cause a lot of requests on your Web server, -due to the *Go Team at Google*'s choice to update the cache quickly (and -therefore avoid stale data). -You may opt-out the proxy by -[contacting a maintainer](https://github.com/golang/go/issues/new). - -> Consider using a more powerful Web server or machine if needed, as the proxy -> is a valuable tool. - -In general, please read [proxy.golang.org](https://proxy.golang.org) for -everything related to the Go proxy and module index. - diff --git a/doc/pages/index.md b/doc/pages/index.md new file mode 100644 index 0000000..1c220d0 --- /dev/null +++ b/doc/pages/index.md @@ -0,0 +1,130 @@ +--- +# Copyright Nicolas (2023) +# +# * Nicolas Paul +# +# This software is a computer program whose purpose is to allow the hosting +# and sharing of Go modules using a personal domain. +# +# This software is governed by the CeCILL license under French law and +# abiding by the rules of distribution of free software. You can use, +# modify and/ or redistribute the software under the terms of the CeCILL +# license as circulated by CEA, CNRS and INRIA at the following URL +# "http://www.cecill.info". +# +# As a counterpart to the access to the source code and rights to copy, +# modify and redistribute granted by the license, users are provided only +# with a limited warranty and the software's author, the holder of the +# economic rights, and the successive licensors have only limited +# liability. +# +# In this respect, the user's attention is drawn to the risks associated +# with loading, using, modifying and/or developing or reproducing the +# software by the user in light of its specific status of free software, +# that may mean that it is complicated to manipulate, and that also +# therefore means that it is reserved for developers and experienced +# professionals having in-depth computer knowledge. Users are therefore +# encouraged to load and test the software's suitability as regards their +# requirements in conditions enabling the security of their systems and/or +# data to be ensured and, more generally, to use and operate it in the +# same conditions as regards security. +# +# The fact that you are presently reading this means that you have had +# knowledge of the CeCILL license and that you accept its terms. + +title: Introduction +description: | + SVGU is a utility tool allowing the sharing and publication of Go modules + on personal domains easily, in a declarative manner. +--- + +# Welcome to SVGU + +**SVGU** (short for *shared vanity Go URLs*) is a neat command-line utility +that allows anyone to publish their Go modules on their own domain, to +obtain names such as `example.com/foo` instead of +`github.com/example/foo`. + +Having a Go module with a custom domain name avoid being trapped to the code +hosting service (such as GitHub). Indeed, you could move to another host or +change the origin without requiring your users to update all their code +to the new path. + +For illustration, imagine you are using `example.com/foo` as a dependency, +whose main origin is on GitHub. If suddenly the origin is moved to GitLab +(for some particular reason), it will be transparent to you. + +## How Does it Work? + +SVGU works by generating a set of HTML files containing the +required meta tags (incl. +[`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) and +[`go-import`](https://go.dev/blog/publishing-go-modules)) by the standard Go +toolchain. These documents also redirects users to the +[Go documentation service](https://pkg.go.dev) for the requested module. + +The resulting output directory can be hosted on any Web server, with the only +required configuration to rewrite URLs to remove the `.html` prefix (some +call this behavior "Pretty URLs"). + +> Here are links to various popular Web servers enabling URL rewriting: +> [Apache HTTPD](https://httpd.apache.org/docs/current/rewrite/remapping.html), +> [Caddy](https://caddyserver.com/docs/caddyfile/directives/rewrite), +> [NGINX](https://www.nginx.com/blog/creating-nginx-rewrite-rules/), +> [Cloudflare Pages](https://pages.cloudflare.com) and +> [GitHub Pages](https://pages.github.com/) do this by default, +> ... + +## Installation + +If you do not see your operating system, use the [Go](#go) or +[compiling from source](#from-source) methods. Also consider contributing +to add your own package manager installation process! + +### Homebrew + +Nicolas Paul maintains an external [Homebrew](https://brew.sh) repository +allowing the installation of SVGU on macOS and some GNU/Linux systems. + +```bash +$ brew install nc0fr/nc0/svgu +``` + +### Go + +The standard Go toolchain can download and install executables directly. +You only need [Go 1.16+](https://go.dev). + +```bash +$ # You can replace latest with any Git ref needed. +$ go install go.nc0.fr/svgu@latest +``` + +### From Source + +Compiling SVGU from source requires [Git](https://git-scm.com) and +[Go](https://go.dev) (1.16 or more). + +First, clone the repository from our GitHub origin: + +```bash +$ git clone https://github.com/nc0fr/svgu.git +$ cd svgu +``` + +Then, build the Go software using `make`: + +```bash +$ make +$ ./svgu -h +``` + +## Licensing + +SVGU is a free software, available under the +[CeCILL 2.1 license](https://cecill.info) contract. +This documentation is available under the +[Creative Commons Attribution-ShareAlike 4.0 license](https://creativecommons.org/licenses/by-sa/4.0/). + +Please see the [repository](https://github.com/nc0fr/svgu) for complete +details. diff --git a/doc/pages/index.mdx b/doc/pages/index.mdx deleted file mode 100644 index 730ad9b..0000000 --- a/doc/pages/index.mdx +++ /dev/null @@ -1,129 +0,0 @@ ---- -# Copyright Nicolas (2023) -# -# * Nicolas Paul -# -# This software is a computer program whose purpose is to allow the hosting -# and sharing of Go modules using a personal domain. -# -# This software is governed by the CeCILL license under French law and -# abiding by the rules of distribution of free software. You can use, -# modify and/ or redistribute the software under the terms of the CeCILL -# license as circulated by CEA, CNRS and INRIA at the following URL -# "http://www.cecill.info". -# -# As a counterpart to the access to the source code and rights to copy, -# modify and redistribute granted by the license, users are provided only -# with a limited warranty and the software's author, the holder of the -# economic rights, and the successive licensors have only limited -# liability. -# -# In this respect, the user's attention is drawn to the risks associated -# with loading, using, modifying and/or developing or reproducing the -# software by the user in light of its specific status of free software, -# that may mean that it is complicated to manipulate, and that also -# therefore means that it is reserved for developers and experienced -# professionals having in-depth computer knowledge. Users are therefore -# encouraged to load and test the software's suitability as regards their -# requirements in conditions enabling the security of their systems and/or -# data to be ensured and, more generally, to use and operate it in the -# same conditions as regards security. -# -# The fact that you are presently reading this means that you have had -# knowledge of the CeCILL license and that you accept its terms. - -title: Introduction -description: | - SVGU is a utility tool allowing the sharing and publication of Go modules - on personal domains easily, in a declarative manner. ---- - -# Welcome to SVGU - -**SVGU** (short for *shared vanity Go URLs*) is a neat command-line utility -that allows anyone to publish their Go modules on their own domains, to -obtain module names such as `example.com/foo` instead of `github.com`. - -Naming a Go module using a custom domain name avoid being trapped to the code -hosting service (such as GitHub). Indeed, you could change the host used (or -change the origin used) without requiring your users to change all their code -to the new path. - -For illustration, imagine you are using `example.com/foo` as a dependency, -whose main origin is on GitHub. If suddenly the origin is moved to GitLab -(for some particular reason), it will be transparent to you. - -## How Does it Work? - -SVGU works by generating a set of HTML files containing the -required meta tags (incl. -[`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) and -[`go-import`](https://go.dev/blog/publishing-go-modules)) by the standard Go -toolchain. These documents also redirects users to the -[Go documentation service](https://pkg.go.dev) for the requested module. - -The resulting directory of files can be hosted on any web server, with the only -required configuration to rewrite URLs to remove the `.html` prefix (some -call this behavior "Pretty URLs"). - -> Here are links to various popular web servers enabling URL rewriting: -> [Apache HTTPD](https://httpd.apache.org/docs/current/rewrite/remapping.html), -> [Caddy](https://caddyserver.com/docs/caddyfile/directives/rewrite), -> [NGINX](https://www.nginx.com/blog/creating-nginx-rewrite-rules/), -> [Cloudflare Pages](https://pages.cloudflare.com) and -> [GitHub Pages](https://pages.github.com/) do this by default, -> ... - -## Installation - -If you do not see your operating system, use the [Go](#go) or -[compiling from source](#from-source) methods. Consider contributing to add -your own operating system installation! - -### Homebrew - -Nicolas Paul maintain an external [Homebrew](https://brew.sh) repository -which allows installing SVGU on macOS and some GNU/Linux systems. - -```bash -$ brew install nc0fr/nc0/svgu -``` - -### Go - -The standard Go toolchain allows installing binaries directly. You only -require [Go 1.16+](https://go.dev). - -```bash -$ # You can replace latest with any Git ref needed. -$ go install go.nc0.fr/svgu@latest -``` - -### From Source - -Compiling SVGU from source requires [Git](https://git-scm.com) and -[Go](https://go.dev) (1.16 or more). - -First, clone the repository from our GitHub origin: - -```bash -$ git clone https://github.com/nc0fr/svgu.git -$ cd svgu -``` - -Then, you can simply build the Go software using `make`: - -```bash -$ make -$ ./svgu -h -``` - -## Licensing - -SVGU is a free software, available under the -[CeCILL 2.1 license](https://cecill.info) contract. -This documentation is available under the -[Creative Commons Attribution-ShareAlike 4.0 license](https://creativecommons.org/licenses/by-sa/4.0/). - -Please see the [repository](https://github.com/nc0fr/svgu) for complete -details. diff --git a/doc/pages/references.md b/doc/pages/references.md new file mode 100644 index 0000000..fb5497b --- /dev/null +++ b/doc/pages/references.md @@ -0,0 +1,186 @@ +--- +# Copyright Nicolas (2023) +# +# * Nicolas Paul +# +# This software is a computer program whose purpose is to allow the hosting +# and sharing of Go modules using a personal domain. +# +# This software is governed by the CeCILL license under French law and +# abiding by the rules of distribution of free software. You can use, +# modify and/ or redistribute the software under the terms of the CeCILL +# license as circulated by CEA, CNRS and INRIA at the following URL +# "http://www.cecill.info". +# +# As a counterpart to the access to the source code and rights to copy, +# modify and redistribute granted by the license, users are provided only +# with a limited warranty and the software's author, the holder of the +# economic rights, and the successive licensors have only limited +# liability. +# +# In this respect, the user's attention is drawn to the risks associated +# with loading, using, modifying and/or developing or reproducing the +# software by the user in light of its specific status of free software, +# that may mean that it is complicated to manipulate, and that also +# therefore means that it is reserved for developers and experienced +# professionals having in-depth computer knowledge. Users are therefore +# encouraged to load and test the software's suitability as regards their +# requirements in conditions enabling the security of their systems and/or +# data to be ensured and, more generally, to use and operate it in the +# same conditions as regards security. +# +# The fact that you are presently reading this means that you have had +# knowledge of the CeCILL license and that you accept its terms. + +title: References +description: | + References and documentation of the SVGU public API. +--- + +# SVGU References + +This document presents the exposed API of SVGU for use within Starlark +configurations. + +## index + +```python +index(domain) +``` + +Index initializes the module registry to host at the given domain. +This function must be called before any [`module()`](#module) function. + +Parameters: + +- `domain` (str): the domain name the repository will be hosted at, e.g. + [go.nc0.fr](https://go.nc0.fr). + +```python +# Modules hosted at example.com` +index(domain="example.com") + +# ... +``` + +## module + +```python +module(name, vcs, repo, dir, file) +``` + +Module registers a module inside the index. A module is defined by its `name`. +Two modules with the same name cannot exist at the same time in the same index. + +A module name must be a valid URL path segment, it cannot be empty, nor +contains dots (`.`), slashes (`/`), backslashes (`\`), colons (`:`), +asterisks (`*`), or ASCII control characters (i.e. `\x00` through `\x1f`) +(required to avoid issues with file systems and URLs). + +The module name cannot also be simply `index`. This is a limitation of the +file generation system. + +Parameters: + +- `name` (str): the name of the module (without the domain and the prefixing + slash), e.g. `"foo/v2"`; +- `vcs` (str): the version control system used to host the code supported by + the standard Go toolchain. Must be one of `"bzr"` ([Bazaar][bzr]), `"fossil"` + ([Fossil][fossil]), `"git"` ([Git][git]), `"hg"` ([Mercurial][hg]), or + `"svn"` ([Subversion][svn]); +- `repo`: the URL of the code repository, e.g. `"https://github.com/foo/bar"`; +- `dir`: a Go template forming the URL to a page listing the various files + inside a directory, e.g. `"https://github.com/foo/bar/tree/main{/dir}"`. + Please refers to the [`go-source`][go-source] for more information about the + - `file`: a Go template forming the URL to a page listing the lines of code + inside a file, and links to a specific line if needed, e.g. + `"https://github.com/foo/bar/blob/main{/dir}/{file}#{line}"`. Please refers to + the [`go-source`][go-source] for more information about the + template template. + +[go-source]: https://github.com/golang/gddo/wiki/Source-Code-Links +[bzr]: https://www.gnu.org/software/bazaar/ +[fossil]: https://www2.fossil-scm.org/home/doc/trunk/www/index.wiki +[git]: https://git-scm.com +[hg]: https://www.mercurial-scm.org +[svn]: https://subversion.apache.org + +Here are valid templates for a few popular hosting services: + +- **GitHub (Git):** `https://///tree/{/dir}` (dir) + and`https://///blob/{/dir}/{file}#{line}` (file); +- **GitLab (Git):** `https://///-/tree/{/dir}` (dir) + and `https://///-/blob/{/dir}/{file}#L{line}` + (file); +- **Source Hut (Git):** `https:///~//tree/{/dir}` + (dir) and + `https:///~//tree//item{/dir}/{file}#L{line}` + (file); +- **Bitbucket (Git):** `https://///src/{/dir}` + (dir) and + `https:////src/{/dir}/{file}#{file}-{file}` + (file); +- **Gitiles (Git):** `https:////+/refs/heads/{/dir}` (dir) + and `https:////+/refs/heads/{/dir}/{file}#{line}` (file); +- **Launchpad (Bazaar):** + `https:///~///files/{/dir}` (dir) and + `https:///~///view/{/dir}/{file}#L{line}` + (file); +- **Source Hut (Mercurial):** + `https:///~//browse{/dir}?rev=` (dir) and + `https:///~//browse{/dir}/{file}?rev=#L{line}` + (file). + +> Do not forget to replace `` with the expected value. + +```python +index(domain="example.com") + +SUBVERSION = "svn" + +# Will be usable in Go as "example.com/foo". +module(name="foo", vcs=SUBVERSION, repo="https://src.example.com/foo", + dir="https://src.example.com/tree/master{/dir}", + file="https://src.example.com/tree/master{/dir}/{file}#{line}") +``` + +## Helpers + +In previous versions of SVGU, a set of Starlark modules (`@svgu/bzr`...) was +exposing a set of macros to help writing configurations for modules hosted +on popular platforms, such as GitHub. + +We decided to remove them due to the burden of maintaining them with the +rational that they are trivial to write. Indeed, the old `git.github()` macro +can be implemented as such: + +```python +def github(name, user, repo, ref = "main", instance = "github.com"): + repo = "https://%s/%s/%s" % (instance, user, repo) + dir = "%s/tree/%s{/dir} % (repo, ref) + + module( + name=name, + vcs="git", + repo=repo, + dir=dir, + file="%s/{file}#{line}" % dir, + ) +``` + +> The same applies to other macro inside other modules, such as +>`bzr.launchpad()` and `hg.sourcehut()`. + +And constants, such as `git.GIT` and `fossil.FOSSIL` are simple variables: + +```python +BAZAAR = "bzr" +FOSSIL = "fossil" +GIT = "git" +MERCURIAL = "hg" +SUBVERSION = "svn" +``` + +It is encouraged to write your own helper functions and constants at the +beginning of your configuration file. + diff --git a/doc/pages/references.mdx b/doc/pages/references.mdx deleted file mode 100644 index fb5497b..0000000 --- a/doc/pages/references.mdx +++ /dev/null @@ -1,186 +0,0 @@ ---- -# Copyright Nicolas (2023) -# -# * Nicolas Paul -# -# This software is a computer program whose purpose is to allow the hosting -# and sharing of Go modules using a personal domain. -# -# This software is governed by the CeCILL license under French law and -# abiding by the rules of distribution of free software. You can use, -# modify and/ or redistribute the software under the terms of the CeCILL -# license as circulated by CEA, CNRS and INRIA at the following URL -# "http://www.cecill.info". -# -# As a counterpart to the access to the source code and rights to copy, -# modify and redistribute granted by the license, users are provided only -# with a limited warranty and the software's author, the holder of the -# economic rights, and the successive licensors have only limited -# liability. -# -# In this respect, the user's attention is drawn to the risks associated -# with loading, using, modifying and/or developing or reproducing the -# software by the user in light of its specific status of free software, -# that may mean that it is complicated to manipulate, and that also -# therefore means that it is reserved for developers and experienced -# professionals having in-depth computer knowledge. Users are therefore -# encouraged to load and test the software's suitability as regards their -# requirements in conditions enabling the security of their systems and/or -# data to be ensured and, more generally, to use and operate it in the -# same conditions as regards security. -# -# The fact that you are presently reading this means that you have had -# knowledge of the CeCILL license and that you accept its terms. - -title: References -description: | - References and documentation of the SVGU public API. ---- - -# SVGU References - -This document presents the exposed API of SVGU for use within Starlark -configurations. - -## index - -```python -index(domain) -``` - -Index initializes the module registry to host at the given domain. -This function must be called before any [`module()`](#module) function. - -Parameters: - -- `domain` (str): the domain name the repository will be hosted at, e.g. - [go.nc0.fr](https://go.nc0.fr). - -```python -# Modules hosted at example.com` -index(domain="example.com") - -# ... -``` - -## module - -```python -module(name, vcs, repo, dir, file) -``` - -Module registers a module inside the index. A module is defined by its `name`. -Two modules with the same name cannot exist at the same time in the same index. - -A module name must be a valid URL path segment, it cannot be empty, nor -contains dots (`.`), slashes (`/`), backslashes (`\`), colons (`:`), -asterisks (`*`), or ASCII control characters (i.e. `\x00` through `\x1f`) -(required to avoid issues with file systems and URLs). - -The module name cannot also be simply `index`. This is a limitation of the -file generation system. - -Parameters: - -- `name` (str): the name of the module (without the domain and the prefixing - slash), e.g. `"foo/v2"`; -- `vcs` (str): the version control system used to host the code supported by - the standard Go toolchain. Must be one of `"bzr"` ([Bazaar][bzr]), `"fossil"` - ([Fossil][fossil]), `"git"` ([Git][git]), `"hg"` ([Mercurial][hg]), or - `"svn"` ([Subversion][svn]); -- `repo`: the URL of the code repository, e.g. `"https://github.com/foo/bar"`; -- `dir`: a Go template forming the URL to a page listing the various files - inside a directory, e.g. `"https://github.com/foo/bar/tree/main{/dir}"`. - Please refers to the [`go-source`][go-source] for more information about the - - `file`: a Go template forming the URL to a page listing the lines of code - inside a file, and links to a specific line if needed, e.g. - `"https://github.com/foo/bar/blob/main{/dir}/{file}#{line}"`. Please refers to - the [`go-source`][go-source] for more information about the - template template. - -[go-source]: https://github.com/golang/gddo/wiki/Source-Code-Links -[bzr]: https://www.gnu.org/software/bazaar/ -[fossil]: https://www2.fossil-scm.org/home/doc/trunk/www/index.wiki -[git]: https://git-scm.com -[hg]: https://www.mercurial-scm.org -[svn]: https://subversion.apache.org - -Here are valid templates for a few popular hosting services: - -- **GitHub (Git):** `https://///tree/{/dir}` (dir) - and`https://///blob/{/dir}/{file}#{line}` (file); -- **GitLab (Git):** `https://///-/tree/{/dir}` (dir) - and `https://///-/blob/{/dir}/{file}#L{line}` - (file); -- **Source Hut (Git):** `https:///~//tree/{/dir}` - (dir) and - `https:///~//tree//item{/dir}/{file}#L{line}` - (file); -- **Bitbucket (Git):** `https://///src/{/dir}` - (dir) and - `https:////src/{/dir}/{file}#{file}-{file}` - (file); -- **Gitiles (Git):** `https:////+/refs/heads/{/dir}` (dir) - and `https:////+/refs/heads/{/dir}/{file}#{line}` (file); -- **Launchpad (Bazaar):** - `https:///~///files/{/dir}` (dir) and - `https:///~///view/{/dir}/{file}#L{line}` - (file); -- **Source Hut (Mercurial):** - `https:///~//browse{/dir}?rev=` (dir) and - `https:///~//browse{/dir}/{file}?rev=#L{line}` - (file). - -> Do not forget to replace `` with the expected value. - -```python -index(domain="example.com") - -SUBVERSION = "svn" - -# Will be usable in Go as "example.com/foo". -module(name="foo", vcs=SUBVERSION, repo="https://src.example.com/foo", - dir="https://src.example.com/tree/master{/dir}", - file="https://src.example.com/tree/master{/dir}/{file}#{line}") -``` - -## Helpers - -In previous versions of SVGU, a set of Starlark modules (`@svgu/bzr`...) was -exposing a set of macros to help writing configurations for modules hosted -on popular platforms, such as GitHub. - -We decided to remove them due to the burden of maintaining them with the -rational that they are trivial to write. Indeed, the old `git.github()` macro -can be implemented as such: - -```python -def github(name, user, repo, ref = "main", instance = "github.com"): - repo = "https://%s/%s/%s" % (instance, user, repo) - dir = "%s/tree/%s{/dir} % (repo, ref) - - module( - name=name, - vcs="git", - repo=repo, - dir=dir, - file="%s/{file}#{line}" % dir, - ) -``` - -> The same applies to other macro inside other modules, such as ->`bzr.launchpad()` and `hg.sourcehut()`. - -And constants, such as `git.GIT` and `fossil.FOSSIL` are simple variables: - -```python -BAZAAR = "bzr" -FOSSIL = "fossil" -GIT = "git" -MERCURIAL = "hg" -SUBVERSION = "svn" -``` - -It is encouraged to write your own helper functions and constants at the -beginning of your configuration file. - -- cgit v1.2.3