-
Notifications
You must be signed in to change notification settings - Fork 88
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve the documentation #258
Conversation
@tcojean, I wanted to publish the documentation generated by this branch |
@pratikvn Yes, the variables used (for the bot login etc) are protected, so the branch needs to be protected for the deployment to work. |
I see. I dont really want to make the branch protected. Do you have any other suggestions ? |
I think protecting the branch is the only safe way. If we unprotect the variables then anyone could access their value through some CI job... You can protect it, launch a CI pipeline, then unprotect it once it is completed. |
Okay. But I don't think I have permissions to make it protected either. I think that should be done through |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Currently, only gko::group
is showing up when you look at the namespaces in doxygen. This is probably because it is commented with doxygen in cooperative_groups.cuh
.
Can you also add comments to the other namespaces in order for them to show up?
I am not sure if it is enough to just comment in one file on a namespace in order for all other functions in other files to show up.
@pratikvn I made the branch protected and ran the documentation generation. See: https://gitlab.com/ginkgo-project/ginkgo-public-ci/-/jobs/176738804 |
@pratikvn it's a nice improvement. I haven't explored everything but there is a bug with the |
Yes, I saw that. Thank you. Regarding the examples tab, that is one thing we have to discuss, I guess. Should we go for a proper tutorial or link to just our examples in the repo. Therefore, for now I left it unlinked. But i will link the wiki as default. |
@pratikvn On the issues you raised, I think the color For the examples tab, I believe the Wiki would be a good place to point to, but nonetheless we may need a full list of the examples (hopefully with documentation) which Ginkgo contains. Is there any way to generate such a thing? It would be great to have a list of examples with short description, eventually links to the related files for each example and there documentation for the class or whatever is implemented (such as the 3pt stencil). I think overall, we should have a page like that for examples and a separate one for tutorial which would point to the wiki entries. A minor point, the header states |
I have updated the color to I have pointed the examples tab to the wiki for now, but as you suggest, we definitely should have a more comprehensive explanation in the documentation. I will see what I can add. The header states the current branch and the version of code. It gets automatically updated from the appropriate cmake variables. So for the master branch, it should say something like master and 1.0.0. I think that is quite useful, so I think we should leave it there. |
@pratikvn the documentation is now updated. Looks like the namespaces are properly fixed among other things. As for the documentation showing |
30f474b
to
1621678
Compare
This is a small PR with the purpose of adding a new tool, [codecov](https://codecov.io/gh/ginkgo-project/ginkgo/branch/add_codecov). This provides the ability to add a coverage banner in our Readme. I also add some other convenience banners at the same time. The codecov tool itself provides a different view of code coverage which is fairly intuitive. See the link above for an example. Here is a sample from the branch: ![Coverage](https://codecov.io/gh/ginkgo-project/ginkgo/branch/add_codecov/graph/badge.svg) Finally, it is unrelated but the containers are updated at the same time to also add the `graphviz` tool which is required for PR #258. Related PR: #264
Currently, in the normal documentation, we also list the |
I would add, and for examples and benchmarks for which documentation would be nice. The things we do not need to generate documentation for (for the public) are in core, cuda, omp and reference, I think. |
…emove whitespaces
…ll, test and bench, Add missing benchmarking.md file
…move commented stuff in filter
…in doc cmake helpers
…icense. Addexception to the add_license script
This PR is concerned with the improvement of documentation in general for Ginkgo using Doxygen. This closes #76 .
Main changes:
Things to discuss:
The different colors for the top title bar. To be set in stylesheet.css
@hartwiganzt has a list of suitable colors to choose from
background 0202ff , 00468b, 003c97
font:#dddddd
How do we incorporate the examples and tutorials ? The wiki currently has an incomplete tutorial that could form the basis for this.
Remove fix-docs from deployment step before merging.
See how it looks here.