Having the fpm registry here directly as part of the fpm documentation would be great. Currently it seems a bit difficult to find as a subcategory of the package index, while having it here seems more natural.

Since the fpm-docs are now dependent on the fpm-registry data which are only fetched on build and afterwards static, we should add a scheduled rebuild to the workflow to keep the registry page up-to-date with the registry index.

We need more How-To guides in the documentation pages. Here are some ideas:

• building an fpm application with MPI
  • --compiler keyword for MPI wrapper
  • external-modules manifest keyword
  • hybrid MPI via preprocessor
• linking against system libraries
  • link manifest keyword
• including C code in a project
  • header placement
  • include-dir manifest keyword

mirgrate to setup-micromamba github action from provision-with-micromamba as the sphinx builds have been failing as the provision-with-micromamba has been deprecated by the mamba-org.

We need more tutorials to cover different aspects of fpm. Here are some ideas:

• adding dependencies: #18
  • build a new project that depends on stdlib
  • add development dependencies and build unit tests with a testing framework with test-drive/vegetables
  • build a command line application with M_CLI2
• using fpm plugins: #36
  • installing fpm-search with fpm
  • querying the registry
  • adding a dependency from the registry

The fpm registry is currently hosted on the webpage, but doesn't really belong in the general package index, as many packages in the fpm registry are also in the package index leading to duplicated.

Instead the fpm docs should host the fpm registry directly.

The weblate language code is hi.

Description

There is a source file scoping specification in the fpm developer specification, but it is somewhat hidden and not obvious, and it is important enough to be included in the user documentation.

Specification contents:

## Source file scoping
Source files are assigned a scope of either FPM_SCOPE_LIB, FPM_SCOPE_APP or FPM_SCOPE_TEST.
The scope controls which modules may be used by the source file:

- Library sources (FPM_SCOPE_LIB) may only use modules also with library scope.
  This includes library modules from dependencies.

- Executable sources (FPM_SCOPE_APP,FPM_SCOPE_TEST) may use library modules (including dependencies)
  as well as any modules corresponding to source files in the same directory
  or a subdirectory of the executable source file.

Links

1. intended design
2. specification
3. Unable to find dependency from parent directory when building exe

@1984logo Do you have a source for the logo we can work with (svg, ...), I would make a start and incorporate it in the fpm documentation as favicon and sidebar logo.

Also, I plan to include a page on the logo itself and how it should be used in the design section.

From fortran-lang/fpm#380 (comment)

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.

Description

There is a source file scoping specification in the fpm developer specification, but it is somewhat hidden and not obvious, and it is important enough to be included in the user documentation.

Specification contents:

## Source file scoping
Source files are assigned a scope of either FPM_SCOPE_LIB, FPM_SCOPE_APP or FPM_SCOPE_TEST.
The scope controls which modules may be used by the source file:

- Library sources (FPM_SCOPE_LIB) may only use modules also with library scope.
  This includes library modules from dependencies.

- Executable sources (FPM_SCOPE_APP,FPM_SCOPE_TEST) may use library modules (including dependencies)
  as well as any modules corresponding to source files in the same directory
  or a subdirectory of the executable source file.

Links

1. intended design
2. source file scoping specification
3. Unable to find dependency from parent directory when building exe

We should try to convert the output of fpm's command line help to markdown and include it in the reference section of the documentation.

Related:

• Cargo's command line help page: https://doc.rust-lang.org/cargo/commands/cargo.html

cc @urbanjost

The documentation follows the Diátaxis framework (https://diataxis.fr/). A short overview in the design section should be added to clarify the four sections the documentation is subdivided in.

This thread tracks the translation of the documentation to Chinese. Feel free to post either in Chinese or English in this threads, whatever seems most appropriate.

此线程跟踪文档的中文翻译。无论看起来是否合适，都可以随时在此帖子中以中文或英文发布消息。

Issues:

• executablebooks/sphinx-book-theme#433

Moin guys,

I'm getting a 404 error when doing the default install route of fpm on my new Mac laptop:

Code/github.com/pgierz
❯ brew tap fortran-lang/fpm
==> Tapping fortran-lang/fpm
Cloning into '/opt/homebrew/Library/Taps/fortran-lang/homebrew-fpm'...
remote: Repository not found.
fatal: repository 'https://github.com/fortran-lang/homebrew-fpm/' not found
Error: Failure while executing; `git clone https://github.com/fortran-lang/homebrew-fpm /opt/homebrew/Library/Taps/fortran-lang/homebrew-fpm --origin=origin --template= --config core.fsmonitor=false` exited with 128.

There appears to also already be a related issue directly in the homebrew repo: fortran-lang/homebrew-fortran#32

Note that this can be worked around, but it would nevertheless be nice if the install instructions were up to date....

Generation of new languages is currently automated using make gettext to update or generate new translations:

https://github.com/awvwgk/fpm-docs/blob/03f2691ddd69c7c4d42b770018eafeec9ef761ea/Makefile#L26-L28

The sphinx-build and sphinx-intl commands take care of most steps from the usual translation workflow, the translator only has to fill in the translations in the po files and check them into the repository.

Relevant links:

• settings for pages/conf.py:
  https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-internationalization
• sphinx-intl:
  https://www.sphinx-doc.org/en/master/usage/advanced/intl.html#intl
• gettext, msgfmt, po-format:
  https://en.wikipedia.org/wiki/Gettext

Once we smoothed out the workflow for translating the documentation, a short recipe with the most important points should be available in the How-To section (could also profit from potential translations).

• The title block doesn't work in awvwgk.github.io/fpm-docs/

en/index.html

de/index.html

zh_CN/index.html

es/index.html

• The language links only work on the page index.html.

I think that the fenced code-blocks in the docs might need to have the ❯ character removed, since copy-pasting the block results into the ❯ character being copied as well thus making the command unable to run upon paste

MacPorts has fpm port. It would be nice if MacPorts is added to an option to install fpm for macOS.

This thread tracks the translation of the documentation to French. Feel free to post either in French or English in this threads, whatever seems most appropriate.

Requested via Weblate. Polish is supported with the language code pl.

Last new language added in #81.

We are relying on a couple of projects in pre-1.0.0 stage, which means minor version bumps are usually API breaking. Right now most of the versions as free, but it might be better to have some version ranged we pin them to.

Hi,

To contribute to internationalizing the fpm-doc, I forked this repository and translated fpm-doc into Japanese.

Committed changes are as follows:

• created .po files in locale/ja.
• translated all the .po files into Japanese.
• added 'ja' like {%- for lang in ('zh_CN', 'de', 'en', 'es', 'fr', 'ja', 'nl') %} in pages/_templates/sbt-sidebar-footer.html.
• added ja to LANGUAGE in Makefile.
• generated using make html and confirmed pages via some browsers.

Is there anything I should do for internationalization?
Is there any work before sending a pull request?

Thank you.

When switching the language a new tab opens. I think it would be better to change the language in the same tab which is already open.

The upstream for fpm-search is gone after Carlos Une has deleted his account. Therefore, the tutorial does not work right now.

I found that John @urbanjost has pushed a fork to https://github.com/urbanjost/fpm-search, which could be used instead.

This thread tracks the translation of the documentation to Spanish. Feel free to post either in Spanish or English in this threads, whatever seems most appropriate.

cc @aslozada

This thread tracks the translation of the documentation to Dutch. Feel free to post either in Dutch or English in this threads, whatever seems most appropriate.

cc @arjenmarkus

Requested via Weblate. Bengali is supported with the language code bn.

Last new language added in #81.

Currently the fpm documentation webpage deploys regardless of the branch we push from!

This needs to be activated again ASAP!

Once this projects has matured, it should be maintained under the @fortran-lang namespace. Preferably it will show up at https://fpm.fortran-lang.org and we can add the API documentation as subtree (https://fpm.fortran-lang.org/api or similar).

This issue should track milestones before we can transfer this repository to @fortran-lang. Feel free to add items with comments below.

Our GitHub actions have been slowly getting outdated. We should enable dependabot alerts and have then run 1/mo to keep things from breaking.

This thread tracks the translation of the documentation to German. Feel free to post either in German or English in this threads, whatever seems most appropriate.

Issues:

• translating the button-ref label will remove the button and the link reference from the main page (reported upstream executablebooks/sphinx-design#44)

Now that we have larger chunks of Fortran source in the docs we need a workflow to test it with fpm to ensure it is working correctly.

@Beliavsky wrote in https://fortran-lang.discourse.group/t/2338/5:

A fifth part could be added: discussions . Most code in stdlib has one or more related issues where it has been discussed. If related discussions were listed for each source file, that would help to fill in the reference information, since people have often provided links to references when discussing algorithms. Reading discussions could also tell users why algorithms were chosen and what the alternatives are.

@certik wrote in https://fortran-lang.discourse.group/t/2338/7:

Excellent idea. Indeed, we should link all discussions for each module in stdlib. I think the discussions are usually related to the whole module, not just a single file.

It’s the same idea behind the GitHub - j3-fortran/fortran_proposals: Proposals for the Fortran Standard Committee repository: to be able to track discussions behind each Fortran feature as it is added to the standard, and features that didn’t make it (and why).

We should include or reference important issues from the design documents or even the reference as appropriate. Let's use this issue to collect important issues and discussions from the fpm repository which should be mentioned in the fpm design documents.