Restructuring of the fpm docs

[gnikit]

I had a look at the fpm docs recently and I believe we need to rethink how the fpm documentation is layed out. There are a few sections that I think need to be worked on.
This is somewhat urgent due to an upcoming blog post from the openmp folks.

1. Manifest page

Has sections for both fpm.toml & config.toml

Meant to define the fields of the fpm.toml, now also contains information about the global configuration file. This should be a separate page Global Configuration File (or something along these lines).

Registry settings section

The registry settings, API expectations and directory structures similarly are not for the fpm.toml but the config.toml and should not be part of the Manifest page. They should live under either a Registry page or Global Configuration File.

Specifying dependencies section

This section is completely mangled and out of order. The information that it contains are not representative of what the user is expected of doing if they want to add dependencies in their projects. A lot of the core information has instead moved under the Registry settings section, which I believe was a mistake. The same applies to the Development dependencies section which is also under Registry settings.

Outdated Adding dependencies section

The section Adding dependencies specifically the stdlib subsection is outdated and does not work anymore.

2. Package upload page

I think since the page is less about fpm and more about the registry functionality through fpm, this page should live somewhere under a Registry page and not alongside the fpm manifest, API and metapackages. The same case can be made for Module name requirements which is geared towards defining rules for valid names for packages in the registry.

3. Registry

Since the STF work on a registry was completed and documented in the fpm docs, now the meaning of the registry in the docs carries a dual meaning, the new not yet fully online registry and the old abandoned registry. fpm docs contains references to both. I am of the opinion that the old Registry page should be removed to minimise confusion from the readers, or better yet replaced with a section that reflects the current registry functionality.

4. Versioning the docs

Since we are introducing breaking changes e.g. with the metapackages I think it would be a good idea to start thinking about versioning the fpm docs. The obvious solution for open-source projects is readthedocs alternatively we could do something like SciPy's API docs although it is substantially more elaborate to get it to work.

---

Edit Suggestions

1. Move all of registry stuff into another page under References or replace existing Registry page (at top level) so that Manifest reference contains only references to fpm.toml. I personally prefer the latter approach (replace existing Registry section).
2. Move Global config options from Manifest into a separate page under Reference with cross-reference links to both Registry and Manifest>Specifying dependencies
3. Move section for dependencies (currently inside Manifest>Registry) inside and at the top of Specifying dependencies with cross-references to the new Registry page
4. Package upload and Module name requirements move inside the Registry page
5. Tutorial updated to reflect metapackages

---

@awvwgk and @LKedward what do you think about the proposed changes, do they seem reasonable?
I will get started on a PR to see how the changes look.

[vmagnin]

What would be the consequences on the translations of the fpm docs?

[gnikit]

What would be the consequences on the translations of the fpm docs?

The only way I can think about maintaining the translations is by:

• finding a way to move the translated content to the new locations
• and not modifying any of the text contents

I was planning on introducing some text changes to make the sections coherent as standalone + adding cross references to other relevant pages. The way I see it is that the impact will be substantial, but we don't really have a choice.

[vmagnin]

This is somewhat urgent due to an upcoming blog post from the openmp folks.

I have just stumbled upon it on Mastodon:
https://www.openmp.org/blog/fortran-package-manager-and-openmp/

[gnikit]

I was about to make a post on Fortran-lang yesterday bringing the article and it's LinkedIn link to the community's attention but i run out of time. I will try and finish it off today.

[vmagnin]

I guess you wrote the text, as it is a very good introduction to fpm.