Restructure Sphinx Doc #1093
Restructure Sphinx Doc #1093
Conversation
- make hierarchy more flat - new categories: basic, advanced, extra info and development - just renamed, delete section, cut out section and put together in another files and changed heading levels - update some internal links
|
for this refactoring the last commit should always contain a CI filter with an empty list. see #1077 |
@psychocoderHPC |
You need to add it to the last commit message of the PR not to the github description. |
What did I wrong now? |
|
@alpaka-group/alpaka-developers |
|
Now, alpaka renders the readthedocs side for each PR, see last entry in the CI list. For this PR, the link is: https://alpaka--1093.org.readthedocs.build/en/1093/ |
|
For some reason I can't comment right there. It seems there is wrong caption formatting just above this with |
|
For the sake of the index I suggest changing this title to just |
|
Great work @SimeonEhrig ! Some comments are above. I can have another look through if needed later. |
|
Thanks @sbastrakov for the great feedback. I think you have found many old errors and some porting errors from the old markdown files in addition to my new errors 😅 |
|
Please find some more comments and questions above. I understand the text is mostly reused from the previous documentation, so did not do all my text suggestions, but just a couple (I can do a follow-up PR for that, as it would be quicker that way). |
| Library Interface | ||
| ================= | ||
|
|
||
| As described in the chapter about the :doc:`Abstraction </basic/abstraction>`, the general design of the library is very similar to *CUDA* and *OpenCL* but extends both by some points, while not requiring any language extensions. |
There was a problem hiding this comment.
General question: Why are we mentioning OpenCL so often? Except for the experimental SYCL backend we have no relationship to OpenCL.
There was a problem hiding this comment.
I think because it was like that at the Master thesis used as a basis for these texts
There was a problem hiding this comment.
Because it was 2015 😎 . Most parts were copied from Benjamin's master thesis. In my opinion, with overworking the text, we should remove a lot of the OpenCL stuff.
| Kokkos provides an abstract interface for portable, performant shared memory-programming. It is a C++ library that offers ``parallel_for``, ``parallel_reduce`` and similar functions for describing the pattern of the parallel tasks. The execution policy determines how the threads are executed. For example, this influences the sizes of blocks of threads or if static or dynamic scheduling should be used. The library abstracts the kernel as a function object that can not have any user defined parameters for its ``operator()``. Arguments have to be stored in members of the function object coupling algorithm and data together. *KOKKOS* provides both, abstractions for parallel execution of code and data management. Multidimensional arrays with a neutral indexing and an architecture dependent layout are available, which can be used, for example, to abstract the underlying hardwares preferred memory access scheme that could be row-major, column-major or even blocked. | ||
|
|
||
|
|
||
| `Thrust <https://thrust.github.io/>`_ |
There was a problem hiding this comment.
Is Thrust really a similar library? I feel that Thrust, ArrayFire, ... are much more high-level than alpaka.
There was a problem hiding this comment.
Well, similar in one way but not on another. I guess this may be left as is, and clarified later.
But I agree they operate on much higher abstraction level, and it's not easy possible to port between those and alpaka
There was a problem hiding this comment.
It's fine by me, but we can remove it. I thought it would be better to keep two rather than one of more than 10 related works (that was CUDA, OpenCL, ...).
There was a problem hiding this comment.
I keep it, because it looks better to have two projects and it is not fully unrelated.
|
@sbastrakov @j-stephan The rest of the outstanding tasks should be done in extra PR. |
|
@SimeonEhrig I do not have objections. |
SimeonEhrig
force-pushed
the
refactorDocs
branch
from
11ef7ff
to
4e93904
Compare
- overworked introduction - integrate cmake example in introduction site to get a good first look on alpaka - split section CUDA GPUs to general GPUs and backend CUDA - overworked similar projects section
SimeonEhrig
force-pushed
the
refactorDocs
branch
from
4e93904
to
774b3c7
Compare
|
Looks good now. @psychocoderHPC This can be merged. |
The current documentation is not well suited for a Sphinx Doc. The refactoring includes two steps:
TODO to merge
This points have to do, that the PR is ready for review. The points handles inconsistencies in the documentation and general structure problems.
TODO for future PRs
This points should be done in future PRs.
ci_filter: [ ]