refactor: logically rearanges section of fpm docs

Fixes #126

Author: gnikit

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

@@ -119,10 +119,15 @@ Browse references
 
 ## {fa}`cubes` Registry
 
-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).
+<!-- TODO: add short description -->
 
+Read about the [fpm registry](registry/index) and how to use it.
+
+::::{note}
+The online registry as part of fpm
+is currently under active development and the online documentation might not be
+up-to-date.
+::::
 
 ## {fa}`newspaper` News
 

pages/registry/index.md

@@ -0,0 +1,17 @@
+(registry)=
+
+# Registry
+
+<!-- TODO: replace URL -->
+
+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/index.rst

@@ -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/naming.md renamed to pages/registry/naming.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/publish.md renamed to pages/registry/publish.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.