Improving the github.io interface #17
Replies: 17 comments 30 replies
-
|
This link is at the top of our repositories page. Can we please clean this up ? It does not look good at all |
Beta Was this translation helpful? Give feedback.
-
|
This repository needs to be cleaned up. The documentation uploaded here should be removed. It does not belong in this repository. |
Beta Was this translation helpful? Give feedback.
-
|
are all the doxygen html files uploaded here ? I have put a number of people here just for discussion. Final task will be assigned later. I just want to get a scope of what is happening here |
Beta Was this translation helpful? Give feedback.
-
|
This is a legacy method to distribute documentation. Using GitHub gh-pages directly provides better results, as mentioned by @aerorahul , because the code team directly controls the documentation and it's all in the same repo. |
Beta Was this translation helpful? Give feedback.
-
|
For NCEPLIBS-bufr and from what I can see for some of the other repos the html files have been generated and stored in gh-pages branches. Is that true ? Can we then just delete the html files loaded here ? @MinsukJi-NOAA can you confirm for me where the html files for NEMS and FV3 dycore are ? |
Beta Was this translation helpful? Give feedback.
-
|
@MinsukJi-NOAA do you have all permissions to do this? |
Beta Was this translation helpful? Give feedback.
-
|
I believe I do, Ratko. Will let you know otherwise. |
Beta Was this translation helpful? Give feedback.
-
Beta Was this translation helpful? Give feedback.
-
|
and here is the link to them https://noaa-emc.github.io/NEMS/ |
Beta Was this translation helpful? Give feedback.
-
|
Each repos documentation currently points to documentation for the most recent release. We can also support multiple releases with gh-pages, with some effort. See https://stackoverflow.com/questions/47643881/github-pages-maintaining-multiple-versions Or this site can be used for the documentation at versions involved in a public release, while the repo gh-pages branch holds the documentation for the most recent release. |
Beta Was this translation helpful? Give feedback.
-
|
We need to have a standard approach for everything. Then the github.io should only contain links to the landing pages |
Beta Was this translation helpful? Give feedback.
-
|
Okay, I will remove the NCEPLIBS part. |
Beta Was this translation helpful? Give feedback.
-
|
Hang, these html files were presumably created a long time ago and should be ok to be deleted right ? Can you please confirm when you have completed this ? |
Beta Was this translation helpful? Give feedback.
-
|
The UPP doc can be found at https://upp.readthedocs.io/en/latest/ |
Beta Was this translation helpful? Give feedback.
-
|
Similar DTC-created documentation for the ufs-weather-model is at https://ufs-weather-model.readthedocs.io/en/latest As I see it the DTC documentation is more "how to set it up and run it" while the Doxygen documentation goes more into the guts of the codes themselves, defining what each module/routine in the code is for , what the input/output files are, and so forth. |
Beta Was this translation helpful? Give feedback.
-
|
In the case of UPP, NCEPLIBS-bufr, and UFS_UTILS, the readthedocs documentation is a high-level documentation, maintained as a separate set of markdown files. The doxygen documentation is very detailed, extending to the level of each function. So the two serve different purposes. We have links to the readthedocs documentation, when it exists, in the README, along with a link to the doxygen docs. We have a long-term goal of combining the two, so that the readthedocs can be generated by doxygen, and are a subset of the doxygen docs. This is not an urgent goal, however. |
Beta Was this translation helpful? Give feedback.
-
|
Regarding UPP, @edwardhartnett summarizes the current documentations correctly. RTD is more user guide "how to" documentation. Those rst files reside within the UPP repo under docs/ and versions are created associated with release branches (for UFS app releases). @edwardhartnett did initial effort to implemetn doxygen standards into UPP codes, but that's as far as we've gotten on that front for inline code detail documentation. I do not know where this https://github.com/NOAA-EMC/NOAA-EMC.github.io/tree/master/UPP/html came from, this is the first I'm seeing it. |
Beta Was this translation helpful? Give feedback.
-
|
I apologize that I'm out of the loop on this, can someone help bring me up to speed? What is the goal of NOAA-EMC.github.io? Just landing page with links to various code bases? Or is it specifically supposed to have detailed code documentation only? Or all documentation? Links to the code repos? Do we anticipate that code-level documentation from doxygen will be created from @edwardhartnett's initial work in the UPP repo and populated here on NOAA-EMC.github.io. Perhaps Valbona's effort was just initial attempt? Please help me understand the goal so we can help make sure all documentations are populating in correct places, without duplication. |
Beta Was this translation helpful? Give feedback.
-
|
Kate I put my reply at the bottom. Can you take a look there ? Sorry. |
Beta Was this translation helpful? Give feedback.
-
|
The EMC web team will be glad to help here once some specifics beyond "clean it up" are provided. What exactly do you want this new page to link to? The most recent documentation (doxygen-generated or otherwise) pages for the various apps? |
Beta Was this translation helpful? Give feedback.
-
|
Yes, I will remove the NCEPLIBS ones, and confirm upon pull request to the
repo.
…On Wed, Aug 18, 2021 at 11:46 AM arun chawla ***@***.***> wrote:
Since this doxygen related documentation was created about 15 months ago,
and as far as I can see is incomplete, my suggestion would be that we
delete these html pages and create the UPP html files in the correct
location (a gh-pages branch in the repo) when the UPP team starts working
on the doxygen documentation. Thoughts ?
—
You are receiving this because you were assigned.
Reply to this email directly, view it on GitHub
<#17 (reply in thread)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AKWSMFAVPEHA7D3KXKSSQTTT5PIW3ANCNFSM5CMGQCVQ>
.
Triage notifications on the go with GitHub Mobile for iOS
<https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675>
or Android
<https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email>
.
|
Beta Was this translation helpful? Give feedback.
-
|
For documentation to a specific tag (I am talking FV3-dycore and NEMS here) we would have to create gh-pages branches at those tags ? |
Beta Was this translation helpful? Give feedback.
-
|
So if you wish to keep historical versions on-line, then perhaps this repo is the best place. In which case, @Hang-Lei-NOAA should not delete these docs, because they represent the state of play when GFS 16 was created, and that's what is desired. |
Beta Was this translation helpful? Give feedback.
-
|
Can we create a gh-pages branch at the tag level ? And then create a static link here ? We only need to worry about the releaser documentation for FV3 and NEMS. The documentation for the libraries can be removed |
Beta Was this translation helpful? Give feedback.
-
|
We can support multiple gh-pages releases. See https://stackoverflow.com/questions/47643881/github-pages-maintaining-multiple-versions. So yes, we can support specific tags (which will point to releases). |
Beta Was this translation helpful? Give feedback.
-
|
OK, I have a suggestion. Currently the NCEPLIBS displays only the most recent version of the documentation (that is, the documentation at the time of the most recent release.) How about we modify that procedure slightly, so that we also preserve the previous versions of the documentation. That way, we will have the documentation for every release. Then this repo can point to a specific version of the documentation, and yet users can find the most recent release, which is probably what they want to see. |
Beta Was this translation helpful? Give feedback.
-
|
What is the proposed action plan here ? Is it a simple case of creating gh-pages branches at the specific tags (if they do not exist yet) ? One step is to clean out the html pages that are in the repository here and move them to the relevant places. The second step is to create an appropriate solution for viewing multiple versions of the documentation |
Beta Was this translation helpful? Give feedback.
-
|
I will work out how to maintain past versions of the docs on the gh-pages branch (see NOAA-EMC/NCEPLIBS-g2c#126 and ufs-community/UFS_UTILS#570, where I will work out the details). This will handle future needs. Future releases can be supported by including links here to the appropriate versions of the documentation, which will all be available. As far as this repo is concerned, does it currently represent the documentation of the released ufs_weather_model? Or some other product? Or is it just a random collection of the software documentation? If the former, then it should be left alone. If the latter than it should be replaced with pointers to the gh-pages branches of the various repos. |
Beta Was this translation helpful? Give feedback.
-
|
for NEMS and FV3 (tagged versions) this place contains the released documentation so this probably needs to stay here. Everything else should be removed. Regardless of that the landing page can be made better |
Beta Was this translation helpful? Give feedback.
-
|
@fossell to help answer your question, no nothing should sit here. The UPP documentation should sit with the UPP repo. This can be a landing page to just be a collection of links (we are still trying to figure that out). Your rst documentation is correct. For doxygen stuff when doxygen is used to create html pages these should sit in a branch called gh-pages in your UPP repo (like its being done for the libraries and UFS-Utils). Putting the html pages here was a mistake and shall be removed. Others please comment |
Beta Was this translation helpful? Give feedback.
-
|
@edwardhartnett any comments on Kate's issue ? |
Beta Was this translation helpful? Give feedback.
-
|
@arunchawla-NOAA - Thank you, this is clear and makes sense. One thing we may want to consider is having different versions of doxygen documentation (e.g. develop branch is different from public-v2 branch, or other implementation branchs). I see this discussed in other comments here. We will probably need some help to set that up properly and get familiar with the procedures are we move forward with doxygen in UPP. |
Beta Was this translation helpful? Give feedback.
-
|
I think the best thing for the UPP documentation would be to do as we do
for NCEPLIBS, and keep it on the gh-pages branch of the repo. WIth a simple
change in repo settings, the gh-pages can be easily displayed by the UPP
software team. It should be updated as part of the release process, so that
it does not represent the UPP develop branch, but instead documents a
released version of the software.
I can help get this going, but I don't have permissions on the UPP repo. I
have an issue up there which describes the need for the gh-pages branch to
host the documentation.
Happy to help further as needed...
Ed
…On Tue, Aug 24, 2021 at 9:04 AM Kate Fossell ***@***.***> wrote:
@arunchawla-NOAA <https://github.com/arunchawla-NOAA> - Thank you, this
is clear and makes sense. One thing we may want to consider is having
different versions of doxygen documentation (e.g. develop branch is
different from public-v2 branch, or other implementation branchs). I see
this discussed in other comments here. We will probably need some help to
set that up properly and get familiar with the procedures are we move
forward with doxygen in UPP.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#17 (reply in thread)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AJIOMMHEHU7Q5SWKFZFMUXDT6OYFFANCNFSM5CMGQCVQ>
.
Triage notifications on the go with GitHub Mobile for iOS
<https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675>
or Android
<https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email>
.
|
Beta Was this translation helpful? Give feedback.
-
|
one of the things we know is how documentation in rst docs can be connected to specific tags using readthedocs. It is not clear how to do that with doxygen and gh-pages. I know Ed you were going to look into it. Maybe once that works for the libraries we can set that up for UPP ? |
Beta Was this translation helpful? Give feedback.
-
@edwardhartnett Can you provide us a link of gh-pages branch for NCEPLIBs? Thanks! |
Beta Was this translation helpful? Give feedback.
-
|
For info about using gh-pages with UPP, see NOAA-EMC/UPP#226 |
Beta Was this translation helpful? Give feedback.
-
|
We already understand how to put URLs into readthedocs documentation, I
believe.
What I am looking into is generating the readthedocs documentation and the
doxygen documentation, automatically, from the doxygen source. This would
eliminate the need for the separate readthedocs high-level documentation we
are now supporting.
However, right now, we can change the readthedocs documentation to include
links the doxygen documentation on gh-pages. I believe this has been done
in the bufr library, for example.
…On Tue, Aug 24, 2021 at 9:39 AM arun chawla ***@***.***> wrote:
one of the things we know is how documentation in rst docs can be
connected to specific tags using readthedocs. It is not clear how to do
that with doxygen and gh-pages. I know Ed you were going to look into it.
Maybe once that works for the libraries we can set that up for UPP ?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#17 (reply in thread)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AJIOMMHRTPZEHAR2NBG5JN3T6O4J7ANCNFSM5CMGQCVQ>
.
Triage notifications on the go with GitHub Mobile for iOS
<https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675>
or Android
<https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email>
.
|
Beta Was this translation helpful? Give feedback.
-
Can we update this ? I cannot see the link to the NCEPLIBS-bufr documentation and there are bullets to things that have no documentation. Plus when I follow the path I get the directories and not the html page links
https://noaa-emc.github.io/
Beta Was this translation helpful? Give feedback.
All reactions