Refactor documentation

.github/workflows/build.yaml

@@ -53,7 +53,7 @@ jobs:
     - name: Setup FPM
       uses: fortran-lang/setup-fpm@v3
       with:
-        fpm-version: 'v0.5.0'
+        fpm-version: 'v0.9.0'
 
     - name: Build all projects
       run: |

pages/conf.py

@@ -40,6 +40,7 @@
     "substitution",
     "html_image",
 ]
+myst_heading_anchors = 5
 
 html_theme = "sphinx_book_theme"
 html_title = "Fortran Package Manager"

pages/how-to/compute-pi-openmp.md

@@ -0,0 +1,51 @@
+# Computing PI with OpenMP
+
+This is a simple example of how to use OpenMP with fpm.
+It is an adapted version of the OpenMP example that can be found
+[here](https://github.com/gjbex/Fortran-MOOC/blob/master/source_code/computing_pi/compute_pi_omp.f90) under a
+[CC-BY-4.0](https://github.com/gjbex/Fortran-MOOC/blob/master/LICENSE) license.
+
+The code approximates the value of PI by performing parallelized numerical
+integration over a quarter of the unit circle.
+The code is structured as follows:
+
+```{literalinclude} ../../src/how-to/compute-pi-openmp/app/main.f90
+:language: fortran
+:caption: app/main.f90
+```
+
+## Using OpenMP as a dependency
+
+To use OpenMP in your project, you need to add the `openmp` dependency to your `fpm.toml` file:
+
+```{literalinclude} ../../src/how-to/compute-pi-openmp/fpm.toml
+:language: toml
+:caption: fpm.toml
+:emphasize-lines: 4-5
+```
+
+OpenMP is a _built-in dependency_ (i.e. metapackage), which means the above
+syntax needs to be used. To find out more about metapackages, see [](../spec/metapackages).
+
+## Building and running the code
+
+To build and run the code, one can use the following commands:
+
+```{code-block} text
+❯ fpm run
+Project is up to date
+Iterations:            10000, PI:         3.141391477611324
+Took:    0.092s, with absolute error:  2.0E-04
+```
+
+And increasing the number of iterations for the approximation while
+simultaneously enabling compiler optimizations with `--profile-release`
+
+```{code-block} text
+❯ fpm run --profile-release -- 1000000000
+main.f90                               done.
+compute-pi-openmp                      done.
+[100%] Project compiled successfully.
+Iterations:       1000000000, PI:         3.141592651589789
+Took:    3.511s, with absolute error:  2.0E-09
+```

pages/how-to/index.md

@@ -2,10 +2,8 @@
 
 # How-To guides
 
-:::{note}
 This section contains practical guides and recipes for solving specific problems with fpm.
-:::
 
 :::{toctree}
-installation
+compute-pi-openmp
 :::

pages/index.md

@@ -117,14 +117,12 @@ Browse references
 
 :::::
 
-## {fa}`cubes` Registry
+## {fa}`cubes` [Registry](registry/index)
 
-There are already many packages available for use with fpm, providing an easily accessible and rich ecosystem of general purpose and high-performance code.
-For a full list of packages checkout the [fpm registry](registry/index).
-New packages can be submitted to the registry [here](https://github.com/fortran-lang/fpm-registry).
+fpm supports local and online registries for downloading dependencies.
+[**Learn more**](registry/index) about the fpm registry and how to use it.
 
-
-## {fa}`newspaper` News
+## {fa}`newspaper` [News](news.md)
 
 Recent events around the Fortran Package Manager, such as new releases, conference talks, and new packages will be announced here.
 

pages/install/index.md

@@ -141,14 +141,14 @@ or from [miniconda](https://docs.conda.io/en/latest/miniconda.html).
 Fpm is available with spack in its develop version.
 To install fpm from spack use
 
-```{code-block}sh
+```{code-block} sh
 spack install fpm
 ```
 
 You can add `+openmp` to enable parallelization of the target compilation in fpm.
 To use fpm in your environment load it with
 
-```{code-block}sh
+```{code-block} sh
 spack load fpm
 ```
 

pages/registry/index.md

@@ -0,0 +1,21 @@
+(registry)=
+
+# Registry
+
+::::{note}
+The online registry as part of fpm
+is currently under active development and the online documentation might not be
+up-to-date.
+::::
+
+Registries are an alternative way for fpm to search and fetch dependencies.
+The default registry is the [official registry](https://registry-frontend.vercel.app/).
+You can also set up your own registry or use a local registry.
+
+The following sections describe how to configure fpm to search for packages in a registry
+
+:::{toctree}
+settings
+publish
+naming
+:::

pages/registry/settings.md

@@ -0,0 +1,47 @@
+(registry-settings)=
+# Settings
+
+The registry settings can be used to customize the registry for all projects. If no registry is specified, the packages will be fetched via HTTP from the [official registry](https://registry-frontend.vercel.app/). The registry settings are specified in the
+[global configuration file](#global-configuration-file).
+
+## Global configuration file
+
+The global configuration file can be used to set default options across all fpm projects on the system. It is, by default, located at `~/.local/share/fpm/config.toml` on Unix-like machines and `%APPDATA%\local\fpm\config.toml` on Windows and must be parsable to a TOML structure. It can be used to configure [registry settings](#settings).
+
+## Registry cache
+
+The registry cache contains the source code of previously downloaded packages. It will first be searched for existing packages that satify the requirements of the requesting project before the package is downloaded. The default cache location is `~/.local/share/fpm/dependencies` on Unix-like machines and `%APPDATA%\local\fpm\dependencies` on
+Windows. The location of the cache can be changed by setting the `cache_path` in the global config file:
+
+```toml
+[registry]
+cache_path = "/path/to/cache"
+```
+
+## Custom registry
+
+If you want to use a custom registry, you can specify it in the global config file:
+
+```toml
+[registry]
+url = "https://my-registry.com"
+```
+
+Your registry must implement the same [API](https://registry-apis.vercel.app/apidocs/) as the official registry.
+
+## Local registry
+
+Use the following configuration if you want to set up a local registry:
+
+```toml
+[registry]
+path = "/path/to/registry"
+```
+
+fpm will search this directory for packages and will not download packages from the internet or fetch packages from the cache.
+
+The directory must be structured the way fpm expects it to be. A package must be located in a directory named after the namespace name, followed by the name of the package and the package version. For example, the package `my-package` with version `0.1.0`, which is part of `my-namespace`, must be located in the directory `<path_to_local_registry>/my-namespace/my-package/0.1.0` on Unix-like systems. The package directory must contain an `fpm.toml` file that has the package metadata. The manifest must therefore be located at `<path_to_local_registry>/my-namespace/my-package/0.1.0/fpm.toml`.
+
+If a specific version is requested, fpm will look for that version in the local registry. If you do not specify a version, fpm will look for the version with the highest precedence.
+
+For instructions on how to set up **project dependencies** in `fpm.toml` when using a registry see

pages/spec/index.md

@@ -12,8 +12,6 @@ The generated API documentation of the fpm internals can be found [here](https:/
 
 :::{toctree}
 manifest
-naming
 metapackages
-publish
 API documentation <https://fortran-lang.github.io/fpm>
 :::