Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-951

Add Doxygen documentation on rebuilds

    Details

      Description

      Master-branch doxygen documentation should be rebuild on every full master build.

        Attachments

          Issue Links

            Activity

            Hide
            robyn Robyn Allsman [X] (Inactive) added a comment -

            The changes for these updates still reside on tickets/DM_271. However, they have been in use on the production site for the last month.

            Robert requested the addition of the doxygen generation capability which was available in the previous rendition of buildbot. Since I was in the midst of porting the simple end-to-end test: demo2012, I also ported the doxygen generator at the same time. The changes necessary in each were similar.

            The diff of the initial entry of the doxygen generation is available at:
            https://dev.lsstcorp.org/cgit/LSST/DMS/devenv/buildbot.git/commit/?h=tickets/DM-271&id=a29677de2f60097f33ac520167f416b14ff282ca

            A second update to standardize the output comments is available at:
            https://dev.lsstcorp.org/cgit/LSST/DMS/devenv/buildbot.git/commit/?h=tickets/DM-271&id=102c3905515a0b786aa900e3af8a43a1756528e4

            The doxygen documentation is currently being generated on every run. There is a block of code which will instead run the doxygen gen only if there was a rebuild of the stack. This change to the initial doxydox release was requested by Robert.

            Show
            robyn Robyn Allsman [X] (Inactive) added a comment - The changes for these updates still reside on tickets/DM_271. However, they have been in use on the production site for the last month. Robert requested the addition of the doxygen generation capability which was available in the previous rendition of buildbot. Since I was in the midst of porting the simple end-to-end test: demo2012, I also ported the doxygen generator at the same time. The changes necessary in each were similar. The diff of the initial entry of the doxygen generation is available at: https://dev.lsstcorp.org/cgit/LSST/DMS/devenv/buildbot.git/commit/?h=tickets/DM-271&id=a29677de2f60097f33ac520167f416b14ff282ca A second update to standardize the output comments is available at: https://dev.lsstcorp.org/cgit/LSST/DMS/devenv/buildbot.git/commit/?h=tickets/DM-271&id=102c3905515a0b786aa900e3af8a43a1756528e4 The doxygen documentation is currently being generated on every run. There is a block of code which will instead run the doxygen gen only if there was a rebuild of the stack. This change to the initial doxydox release was requested by Robert.
            Hide
            robyn Robyn Allsman [X] (Inactive) added a comment -

            This Issue covers the generation of doxygen-based documentation extracted from the build packages.

            The implementation is a port of the script from the previous BB system.

            There are additional refinements to be done in another Issue (DM-1044):

            • restructure the public website to simplify users' ability to find the document version they are seeking. This might be by mapping to a bNNN, date or Release tag.
            • on each 'official' DM Release, capture the doxygen documentation under the name of the Release.
            Show
            robyn Robyn Allsman [X] (Inactive) added a comment - This Issue covers the generation of doxygen-based documentation extracted from the build packages. The implementation is a port of the script from the previous BB system. There are additional refinements to be done in another Issue ( DM-1044 ): restructure the public website to simplify users' ability to find the document version they are seeking. This might be by mapping to a bNNN, date or Release tag. on each 'official' DM Release, capture the doxygen documentation under the name of the Release.
            Hide
            rowen Russell Owen added a comment -

            I'm afraid I'm not finding the code sufficiently clear to say anything intelligent about it. This is not helped by my lack of expertise in shell scripting (and from that biased viewpoint the code looks rather complex to be written as a shell script). Frankly, if it's working then my opinion is you may as well merge it. But if you want a more intelligent assessment then I suggest you find a reviewer more familiar with the code, or at least more familiar with shell scripting.

            Show
            rowen Russell Owen added a comment - I'm afraid I'm not finding the code sufficiently clear to say anything intelligent about it. This is not helped by my lack of expertise in shell scripting (and from that biased viewpoint the code looks rather complex to be written as a shell script). Frankly, if it's working then my opinion is you may as well merge it. But if you want a more intelligent assessment then I suggest you find a reviewer more familiar with the code, or at least more familiar with shell scripting.
            Hide
            robyn Robyn Allsman [X] (Inactive) added a comment -

            Russell,
            Thanks for your candid remarks. I can't deny that it is a wrapper shell script which uses a non-branching sequence of shell commands to generate the documentation and store it away. The nightmare portion of the code is the movement of the actual document into the web service repository. Happily that whole section that will be gutted when DM-1044 is implemented.

            Yes, this ported script is installed and operational in the production system. The DM doxygen documentation is produced by it.

            I will move this to done and later ask for a full code review when the second half of the script is rewritten in DM-1044.

            Show
            robyn Robyn Allsman [X] (Inactive) added a comment - Russell, Thanks for your candid remarks. I can't deny that it is a wrapper shell script which uses a non-branching sequence of shell commands to generate the documentation and store it away. The nightmare portion of the code is the movement of the actual document into the web service repository. Happily that whole section that will be gutted when DM-1044 is implemented. Yes, this ported script is installed and operational in the production system. The DM doxygen documentation is produced by it. I will move this to done and later ask for a full code review when the second half of the script is rewritten in DM-1044 .

              People

              • Assignee:
                robyn Robyn Allsman [X] (Inactive)
                Reporter:
                robyn Robyn Allsman [X] (Inactive)
                Reviewers:
                Russell Owen
                Watchers:
                Robyn Allsman [X] (Inactive), Russell Owen
              • Votes:
                0 Vote for this issue
                Watchers:
                2 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:

                  Summary Panel

                    Time Tracking

                    Estimated:
                    Original Estimate - 1 week
                    1w
                    Remaining:
                    Remaining Estimate - 0 minutes
                    0m
                    Logged:
                    Time Spent - 1 week
                    1w