Refactor and Improve Documentation

changed milestone to %Release 2.0

added documentation label

assigned to @da15siwa

changed the description

requested review from @ab04unyc

added 8 commits

92cd62ba...f2d82bf0 - 6 commits from branch v2.0-dev
9cb46e2d - Merge branch 'v2.0-dev' into fhennig/documentation-update
5ca45f2b - fix doc errors from recent merge

Compare with previous version

List of remarks:

I think it is not clear what the difference between Reference Guide and Developer’s Reference: Code Generation Backend is. I would assume the first is for pystencils users while the latter for pystencils developer?
If the previous point is true, I think it would be helpful to have the option to search in either of them - if possible. The search functionality proposes mostly what I assume is the automatically generated documentation from the doc strings, which are in most cases not helpful if I look for a functionality.
Installation guide is missing.
I don't know if this is necessary for a documentation, but Impressum is missing.
The new documentation look so so so much nicer than the old one.
We could include a list of frameworks using pystencils, waLBerla, lbmpy, HOG, ...?
We could include a cheat sheet with the most important pystencils functions for users that are new to pystencils? (E.g. fields, Targets, KernelParameter, CreateKernelConfig, Checklist for a pystencils code)

Point: Create a welcome page with general information about the project

I like the style of the welcome page a lot. However, I think it would be very helpful to link to the respective chapters in the documentation. E.g.
Make use of pystencils’ discretization engines to automatically derive finite difference- and finite volume-methods ...
I can't even find this engine or what it refers to in the documentation. Maybe not described yet?
... and take control of numerical precision using the versatile type system.
Link to backend (CPU/GPU/vextorizer) -> KernelCreation/Targets (found it later on)
As I understand it, the point Code Generation is basically Reference Guide/Kernel Creation
Example how to export kernels into HPC frameworks.
Framework Integration sentence "Power your [] simulations by ..." sounds like an advertisement, and it is not clear what is meant by it. I would prefer "Improve" or "Accelerate".
What kind of programming languages are supported? C and python?

Reference Guild

Symbolic Language

It is hard to say if the documentation is thorough enough. I would suggest thinking of a way to let users write questions and doubts to the documentation and extend it if necessary. There were some points where I thought, that it might not be too clear how and when to use some pystencils functionalities, but on the other hand, I also thought that it is probably self-explanatory once you do the tutorials and try it out yourself. e.g. sympyextensions seems to me as if they are used by pystencils internally and are not usually not meant to be used by the user? But I'm not sure if this is the case, as some (e.g. math.normalize_product) sound like they are used regularly by the user. And the AssignmentCollection seems really cryptic to me, but I'm sure once you use it, it is totally clear.

Kernel Creation

I think this is self-explanatory, clean and nice.

Type System

The Version 2.0 Migration Guide mentions:

Directly using any of these type classes in the frontend is discouraged unless absolutely necessary; in most cases, create_type suffices.

I would add this information to the Type System in the Reference Guide as well.

Developer’s Reference: Code Generation Backend

Is this doxygen generated? I only gave it a quick glance, but it seems very well documented. Unless there were changes within this MR that need further reviewing, I would not give it a deeper glance.

Tutorials

I did not go through the tutorials, as they were not mentioned in the MR contributions, but I'll go through them at another time and adjust and extend them if necessary.

added 1 commit

ce144c4a - minor fixes to docs

Compare with previous version

It is true that the Reference Guide is meant for users, and the backend reference primarily for developers and power-users. I don't think it is possible to separate them in the search, but I'll try to look into it.
The installation guide and 'cheat sheet' could be combined into a brief "Getting Started" page, listed before the tutorials (or replacing the tutorials? I'm not quite sure what to do with them yet.)
I'm not sure about the Impressum (imprint) either, but I've hardly seen any of these on documentation pages. I'll try to find some info about that.
Some of the things you describe as missing are indeed not part of the docs yet, but will be (auto-discretization, for example).

On the reference guide: At the moment, this is mostly a listing of APIs. I'm working on extending this with explanatory text, giving context to all the classes and functions. In the end, this section should contain a comprehensive reference (APIs and explanations) of all the user-facing APIs of pystencils.

Codegen backend: This is, same as the rest, handwritten + auto-generated from docstrings using autodoc.

Thanks for the extensive review! I've fixed some of the smaller problems you've mentioned. The rest is really missing text and pages that will be added in the coming weeks.

Depending on what you prefer, I would either gather missing parts of the documentation in an issue via link to this and upcoming MRs, or just remember that there were additional information on merged MRs that are labeled with documentation. The documentation that you build up is nicely written and comprehensive. The missing extensions will come over time, so I would merge at this point.

You can merge it; and creating an issue for tracking the state of the documentation is a good idea, I think.

approved this merge request

mentioned in commit 348d606c

merged

resolved all threads

Admin message