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/index.md

@@ -5,7 +5,3 @@
 :::{note}
 This section contains practical guides and recipes for solving specific problems with fpm.
 :::
-
-:::{toctree}
-installation
-:::

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>
 :::

pages/spec/manifest.md

@@ -480,71 +480,6 @@ Dependencies can be declared in the *dependencies* table in the manifest root or
 When declared in the manifest root the dependencies are exported with the project.
 
 
-### Local dependencies
-
-To declare local dependencies use the *path* entry.
-
-```toml
-[dependencies]
-my-utils = { path = "utils" }
-```
-
-The local dependency path is given relative to the ``fpm.toml`` it is written to, and uses ``/`` as the path separator on all platforms.
-
-### Dependency-specific macro setting
-
-As of ``fpm>=0.9.1``, an array of dependency-specific macros can be passed to a single dependency from the manifest, in the same fashion as in the manifest's [preprocessor configuration](#preprocessor-configuration) table. Its `preprocess` table needs to be entered as part of the dependency entry. fpm will not check if the passed macros collide with the dependencie's own manifest, so, it is the user's responsibility to ensure that no collisions or unexpected behavior occur. 
-For example, one can control the `REAL` precision that one library is to be used with: 
-
-```toml
-[dependencies]
-fftpack = { git="https://github.com/fortran-lang/fftpack.git", preprocess.cpp.macros = ["REAL32"] }
-```
-
-## Global config 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](#registry-settings).
-
-## Registry 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 config file](#global-config-file).
-
-### 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](#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.
-
 ### Dependencies from version control systems
 
 Dependencies can be specified by the projects git repository.
@@ -585,6 +520,11 @@ rev = "2f5eaba864ff630ba0c3791126a3f811b6e437f3"
 ```
 ### Dependencies from a registry
 
+:::{note}
+To enable the usage of a registry in fpm make sure you read the instructions
+in the [registry section](../registry/index.md) first.
+:::
+
 #### Namespace
 
 Packages obtained from a registry (both remote and local) are required to specify a namespace, which provides a way to uniquely identify and differentiate packages with identical names. The namespace is declared in the manifest (`fpm.toml`).
@@ -606,6 +546,27 @@ example-package.namespace = "example-namespace"
 example-package.v = "1.0.0"
 ```
 
+### Local dependencies
+
+To declare local dependencies use the *path* entry.
+
+```toml
+[dependencies]
+my-utils = { path = "utils" }
+```
+
+The local dependency path is given relative to the ``fpm.toml`` it is written to, and uses ``/`` as the path separator on all platforms.
+
+### Dependency-specific macro setting
+
+As of ``fpm>=0.9.1``, an array of dependency-specific macros can be passed to a single dependency from the manifest, in the same fashion as in the manifest's [preprocessor configuration](#preprocessor-configuration) table. Its `preprocess` table needs to be entered as part of the dependency entry. fpm will not check if the passed macros collide with the dependencie's own manifest, so, it is the user's responsibility to ensure that no collisions or unexpected behavior occur. 
+For example, one can control the `REAL` precision that one library is to be used with: 
+
+```toml
+[dependencies]
+fftpack = { git="https://github.com/fortran-lang/fftpack.git", preprocess.cpp.macros = ["REAL32"] }
+```
+
 ### Development dependencies
 
 Development dependencies allow to declare *dev-dependencies* in the manifest root, which are available to all tests but not exported with the project.

pages/tutorial/dependencies.md

@@ -78,7 +78,7 @@ The *test-drive* package is added in the *dev-dependencies* table as shown below
 :language: toml
 :caption: fpm.toml
 :lines: 1-10
-:emphasize-lines: 8-10
+:emphasize-lines: 7-9
 ```
 
 :::{note}
@@ -112,7 +112,7 @@ This can be used for adding a command line interface package, which is only used
 ```{literalinclude} ../../src/tutorial/dependencies/fpm.toml
 :language: toml
 :caption: fpm.toml
-:emphasize-lines: 14-15
+:emphasize-lines: 13-14
 ```
 
 We restructure our main program a bit for using [M\_CLI2] to handle the command line input.
@@ -130,14 +130,13 @@ Our final main program looks like
 Again we run a quick check using fpm
 
 ```{code-block} text
-:emphasize-lines: 2, 14
+:emphasize-lines: 2, 12
 ❯ fpm run -- demo substitute fpm.toml
 name = "substitute"
 version = "0.1.0"
 
 [dependencies]
-stdlib.git = "https://github.com/fortran-lang/stdlib"
-stdlib.branch = "stdlib-fpm"
+stdlib = "*"
 
 [dev-dependencies]
 test-drive.git = "https://github.com/fortran-lang/test-drive"

src/tutorial/dependencies/fpm.toml

@@ -2,8 +2,7 @@ name = "demo"
 version = "0.1.0"
 
 [dependencies]
-stdlib.git = "https://github.com/fortran-lang/stdlib"
-stdlib.branch = "stdlib-fpm"
+stdlib = "*"
 
 [dev-dependencies]
 test-drive.git = "https://github.com/fortran-lang/test-drive"