FAQ section in documentation

[lkluft]

It would be nice to have a frequently asked questions (FAQ) section in the typhon documentation.

Purpose

The FAQ section could be used as an application-oriented collection of examples. First ideas would be:

• How do I read and write XML files?
• How do I create an atm_fields_compact?
• How to get started with the ARTS C API?
• ...

Implementation

The implementation should be easily extendable and as automatic as possible. Maybe one can simply add a directory faq (in doc) which could store a single rst-file for each question.

Ideally, these files are included into the documentation without having to update an index by hand.

I will have a look at this at some point. But if there are any Sphinx experts around, I am open to suggestions 😉

Cheers,
Lukas

[JohnMrziglod]

I think this is a very good idea since many modules' docstrings lacking of explicit examples how to apply their classes or functions.

I would like to add some tutorials for my modules as well, but they would be quite extensive and may not really fit into the short FAQ section. What do you think of one FAQ and one Tutorials section? The FAQ may cover many simple examples and may refer to more detailed tutorials for further questions.

[JohnMrziglod]

@lkluft According to http://www.sphinx-doc.org/en/stable/markup/toctree.html (Additional options) one can give a glob option to the toctree command. All matching files are then automatically inserted.

FAQ
===

A collection of FAQ for the usage of typhon modules.

.. toctree::
   :maxdepth: 1
   :glob:

   faq/*

[lkluft]

[...] many modules' docstrings lacking of explicit examples how to apply their classes or functions.

I totally agree with you. The problem is often the difference between the use of a function and it's usage in actual applications. While the former can be captured in short one-liner snippets in the docstring, the latter takes some more effort. That's where your tutorials come into play 😉

I would like to add some tutorials for my modules as well, but they would be quite extensive and may not really fit into the short FAQ section. What do you think of one FAQ and one Tutorials section?

I support this idea. But we have to make a conscious decision what is a FAQ and what's a tutorial. In my opinion, a FAQ serves the additional purpose to guide users, who don't know for what tutorial they are looking. For example

• FAQ: How to construct an atm_fields_compact?
• Tutorial: Initialization and usage of a GriddedField4?

are basically the same thing.
Probably, one could have both and simply link to the tutorial page in the FAQ.

According to http://www.sphinx-doc.org/en/stable/markup/toctree.html (Additional options) one can give a glob option to the toctree command. All matching files are then automatically inserted.

That would be very handy! I think that the mechanism has to be as easy as possible in order for developers to use it regularly.

I assigned both of us to this issue (hope this is fine with you). It seems like you already implemented the Sphinx infrastructure. Anyhow, I am happy to help and at least contribute one or two paragraphs (e.g. the atm_fields_compact one mentioned above).

[JohnMrziglod]

Fixed in #36