Starting the fpm user documentation

Announcements
1

I started working on a page for the fpm user documentation. There is a lot of work that still needs to be done and various details that must be figured out, but the general structure is already in place:

  1. four main parts of documentation: tutorials, recipes, design and references.
  2. multilingual support (English and a partial German translation)
  3. a news section to announce new releases, conference talks and new packages

The repository can be found here

I also put up a preview.

I’m building with sphinx and myst-markdown, all you need to get started is actually a conda installation:

conda env create -n sphinx -f environment.yaml
conda activate sphinx

Help is very welcome, feel free to contribute tutorials or recipes, help us formulate the design principles behind fpm or improve the references and specifications.

Also, we can translate the docs :tada:. If you would like to contribute a translation, just search for the de identifiers in the Makefile and the pages/conf.py to add a new language and run

make gettext

The po files will appear in the locale/<lang> directory and you can start translating!

11 Likes
2

I can help with translations to Spanish, if there is interest in that.

2 Likes
3

@tomohirodegawa has just created Examples of Fortran-stdlib. The readme.md is in Japanese, and Google Translate in Chrome can nicely render it in English. Someone could fork it and create an English version.

1 Like
4

You are very welcome, thanks. I invited you to the repository as collaborator, this should allow you to manage issues.

I opened an issue for a Spanish translation as well, anyone is of course welcome to join this effort.

I don’t speak Spanish, so I won’t be of much help here, other than helping with the technical details.

2 Likes
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.

2 Likes
6

Discussion fit well in the existing categories, they would be part of the design documents for explaining the background of the respective parts of fpm.

I’m also planning to have some meta-documentation on the docs themselves to clarify points like this, see

Thanks to Vincent @vmagnin for bring this framework to my attention.

1 Like
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).

8

I updated the documentation with a tutorial for using dependencies in fpm: Adding dependencies — Fortran package manager. Feedback is very welcome. Also, I’m looking for other tutorial and how-to ideas (maybe we can do a tutorial using fftpack?).

Thanks to @zoziha and @alozada we now have also multilingual fpm documentation. Most pages are available in Chinese, Spanish and German. Let us know how good we are doing with those translations, at least for me writing technical documentation in German is kind of a new thing :sweat_smile:

While building up the pages we stumbled upon a couple of issues with the framework we are using

I hope we can contribute fixes to the upstream projects, but unfortunately they were not really responsive yet.

6 Likes
9

Nice. In the section on dependencies, a link to the fpm registry and a mention of fpm-search would be nice. Note there is a getline function in M_io. The examples could be added to the
fpm example repostory, or a new repository could be started with the examples.

2 Likes
10

Good idea, I will look into writing a tutorial for using fpm plugins using fpm-search and interacting with the registry as example. Added it to the list in [pull] main from fortran-lang:main by pull[bot] · Pull Request #6 · awvwgk/fpm-docs · GitHub.

I was hoping we can add one to stdlib: Procedure to read whole line to deferred length character · Issue #595 · fortran-lang/stdlib · GitHub. Do you want to propose the implementation from M_io for inclusion in stdlib?

The source code for the tutorial is available here as fpm project. I’m using a literalinclude in the tutorial source to include parts of the source code as needed, with the right structuring I can incrementally build up files like the package manifest while walking the reader through the steps.

The first manifest for example is created with

```{literalinclude} ../../src/tutorial/dependencies/fpm.toml
:language: toml
:caption: fpm.toml
:lines: 1-6
:emphasize-lines: 4-6
```

Next step is set up a separate workflow to test all example Fortran source to verify it keeps working.

1 Like
11

The basic idea of the two getlines is the same except mine is implemented as a function instead of a subroutine, so assuming it will be discussed it does not matter what it starts with much. I actually thought there was one in like that in stdlib already. Mine does a few odd things with using a local string and then copying it to the output at the end because of some old issues with allocatable character variables. A few things to note is that the algorithm does not work robustly if PAD=‘YES’ is not set on the input file, and that if the file is not open as a stream you technically run into problems if the system line length limit is hit; but there is no good way to open stdin as a stream in Fortran. Now-adays those limits are set so large they are very unlikely to cause a problem, and it is somewhat up to the compiler what happens anyway.

12

I moved the fpm documentation to the Fortran-lang GitHub org, now it is really official:

Next step is to put it up under https://fpm.fortran-lang.org (done :tada:)

8 Likes
13

This is a very good idea and makes some things clearer for me. I have a request:

As a solely Windows user I have never used a package manager and did not even know about such tools until I started looking at Python. Is it maybe possible to add an introduction that explains what it is, the need for a package manager and why I need it on Windows. A large number of Windows users work only in tools like Visual Studio and never do any compiling or running from a command window.

2 Likes
14

There have been experiments with an fpm gui

and other discussions about how to integrate fpm into IDE packages. Are you more interested in
how to use fpm from IDEs and GUIs or the pros of using a terminal/CLI interface? I think both topics would be good to have materials gathered into tutorials on, but given the choice which are you most interested in?

15

Sebastian @awvwgk , I have now some time to work on a French translation of fpm-docs. I have successfully forked it and configured it for French, except that I don’t see anything related to language identifiers in pages/conf.py. And in the left margin of the compiled site, the “fr” identifier does not appear (but I can access file:///home/osboxes/fpm-docs/_build/html/fr/index.html with my browser).

I plan to use poedit and DeepL to accelerate the work (I have found 246 text blocks to translate).

Any help for the French translation will of course be welcome :slight_smile:

1 Like
16

Thanks a lot, feel free to open a tracking issue.

I moved the language navigation to a template rather than keeping it the conf.py file, which seems more robust:

If you search for one of the existing language identifiers you can find the two relevant places (I still have to document the process in detail):

❯ rg zh_CN .
./Makefile
4:LANGUAGES     ?= en de zh_CN es

./pages/_templates/sbt-sidebar-footer.html
5:    {%- for lang in ('zh_CN', 'de', 'en', 'es', ) %}
1 Like
17

Done!

And I have successfully edited pages/_templates/sbt-sidebar-footer.html

1 Like
18

@awvwgk
I have just forked the latest fpm-docs.
If I just put fr in the Makefile and in pages/_templates/sbt-sidebar-footer.html, then type the $ make gettext command, I can see that some files of the other languages are also modified:

$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   Makefile
	modified:   locale/de/LC_MESSAGES/index.po
	modified:   locale/es/LC_MESSAGES/index.po
	modified:   locale/zh_CN/LC_MESSAGES/index.po
	modified:   locale/zh_CN/LC_MESSAGES/tutorial.po
	modified:   pages/_templates/sbt-sidebar-footer.html

I am confused and I don’t know if this is OK.

For example, the git diff command shows in the locale/de/LC_MESSAGES/index.po file changes like:

-#: ../../pages/index.md:122
+#: ../../pages/index.md:123
+msgid "{fa}`cubes` Registry"
+msgstr ""
+
+#: ../../pages/index.md:125
+msgid ""
+"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](https://fortran-lang.org/packages/fpm). New packages can be "
+"submitted to the registry [here](https://github.com/fortran-lang/fpm-"
+"registry)."
+msgstr ""
+
+#: ../../pages/index.md:130
 msgid "{fa}`newspaper` News"
 msgstr "{fa}`newspaper` Aktuelles"
 
-#: ../../pages/index.md:124
+#: ../../pages/index.md:132

Should I commit only the changes in the fr files? Or commit all?

19

The gettext target will always update all po files, in case they don’t match the latest page source anymore. Which is okay, just ignore the language files you are not interested in.

1 Like
20

@Arjen I opened an issue for a Dutch translation of the fpm docs:

Let me know if you have any questions regarding the workflow to add a new language. It is not properly documented yet ;), but you can find some hints in this thread already. This is something I really have to fix (Document localisation and internationalisation workflow · Issue #5 · fortran-lang/fpm-docs · GitHub).