> On Feb. 24, 2018, 12:50 a.m., Benjamin Mahler wrote: > > Vinod and I went over this, a couple of issues: > > > > * The [endpoint > > documentation](http://mesos.apache.org/documentation/latest/endpoints/) is > > only being generated for latest (see > > https://github.com/apache/mesos/blob/master/support/mesos-website/build.sh), > > this needs to be generated for each version. > > * The C++ and Java API documentation is only being generated for latest > > (not sure how easy this is to fix, maybe if you also tackle this do so in a > > seperate patch). Also note that home.md linked directly to > > "/api/latest/c++" and "/api/latest/java" which means that the old versions > > would send users to latest c++ and java docs. > > * We had a hard time figuring why some of the code changes were needed or > > what they were doing (e.g. some of the new regexes, or why the version > > selector drop-down has an empty value for the first entry), some comments > > would be helpful for the reader. > > > > We were thinking the following approach would be good alternative: > > > > * In order to ensure that we generate the HTTP help endpoint documentation > > correctly for each version, the > > [build.sh](https://github.com/apache/mesos/blob/master/support/mesos-website/build.sh) > > script would loop over each 1.x.y tag (excluding -rc#'s) and checkout the > > tag into a sub-directory. Within this sub-directory, we would build mesos > > and generate the help endpoints documentation. This sub-directory would > > probably be named directly as the version (e.g. "1.0.0", "1.4.1", etc). > > * Note that for efficiency reasons (it's very expensive to build mesos for > > so many tags), the build.sh script would skip a tag if it finds that the > > publish directory already exists for the version in the mesos-site > > repository. > > * The Rakefile would be updated to look at each version checkout > > subdirectory, and would generate the docs using the documentation folder > > within that specific version subdirectory. > > * Not sure if the releases YAML still needs the docs tag, it seems so since > > it's used in the javascript. This would at least need to be updated so that > > everything before 1.0.0 is "false". > > * Is it possible to put the version selector on the right side of the blue > > banner? > > Tim Anderegg wrote: > Sounds good. I had initially avoided the C++ and Java API documentation > since it would take a very long time to generate, as you mention, but I'm > happy to tackle that as well. Limiting to 1.0.0+ will alleviate that a bit. > > For the regex, the first change was just a simplification since the two > lines were redundant once I updated the code to use "{{ version }}" instead > of "latest" (I will verify that however, in case I am remembering > incorrectly). The second change was to account for older versions of the > Mesos code where "latest" was hardcoded into the HTML templates themselves, > which would mess up the links. That one is already commented, but I will go > through and add comments wherever there may be ambiguity. Since we are now > doing only 1.0.0+, this work around can probably be removed. > > For the version selector, happy to move it and remove the empty option, > since the value should always be the currently displayed version of the > documentation. I'm also not sure why I did that, it was a while ago... > > For the docs tag, we could either keep it or if we want the logic to just > be "all versions from 1.0.0 onwards", that can be hard coded into the > build.sh and the HTML template, and we could remove the docs tag. Let me > know what you prefer. > > For the updated approach, just to make sure I'm clear: > > 1) In build.sh, iterate over all tags and checkout the code into a folder > with the tag name, (perhaps in $WORKSPACE/mesos/_build/x.y.z/) if the primary > $WORKSPACE/mesos/site/publish/documentation/x.y.z folder doesn't already > exist. > 2) Then the Rakefile (from $WORKSPACE/mesos, i.e. the HEAD version) is > used to build the docs for each version folder into the primary > $WORKSPACE/mesos/site/publish/documentation/x.y.z folder, as before, but only > if it doesn't already exist. > > A few questions: > > 1) I'm assuming that this build occurs in a Jenkins job that retains its > workspace between runs, which is why we are checking whether or not the > folder exists? Or is the mesos-website publish folder the only thing that > persists between runs? Just want to make sure my conception of the build > environment is correct, if the later is true question 2 can be ignored. > 2) Should the script remove the checked-out code after the build runs for > each version that needed it? Otherwise over time many copies of the Mesos > code would persist (one for each tagged version), which would be GB's in size. > > Thanks! I should be able to find time to do this over the next week or > so. > > Tim
> For the docs tag, we could either keep it or if we want the logic to just be > "all versions from 1.0.0 onwards", that can be hard coded into the build.sh > and the HTML template, and we could remove the docs tag. Let me know what > you prefer. Both sound ok to me, the advantage of the docs tag in the YAML seems to be that we have some more control to disable specific releases if there ever were some issues (e.g. we did a bad .patch release with screwed up documentation, but it was missed during the VOTE). > 1) I'm assuming that this build occurs in a Jenkins job that retains its > workspace between runs, which is why we are checking whether or not the > folder exists? Or is the mesos-website publish folder the only thing that > persists between runs? Just want to make sure my conception of the build > environment is correct, if the later is true question 2 can be ignored. I believe the CI bot will start with a fresh working space each time. The directory that gets "persisted" is only the folder within the mesos-site "publish" directory as you said. > Thanks! I should be able to find time to do this over the next week or so. Awesome! Let us know if that changes or if you want any more discussion :) - Benjamin ----------------------------------------------------------- This is an automatically generated e-mail. To reply, visit: https://reviews.apache.org/r/52064/#review198236 ----------------------------------------------------------- On Feb. 13, 2018, 3:44 p.m., Tim Anderegg wrote: > > ----------------------------------------------------------- > This is an automatically generated e-mail. To reply, visit: > https://reviews.apache.org/r/52064/ > ----------------------------------------------------------- > > (Updated Feb. 13, 2018, 3:44 p.m.) > > > Review request for mesos, haosdent huang and Vinod Kone. > > > Bugs: MESOS-3011 > https://issues.apache.org/jira/browse/MESOS-3011 > > > Repository: mesos > > > Description > ------- > > This patch updates the website build process to allow for documentation to be > generated for all versions of Mesos, based on the existing Git tags. > Additionally, the website is updated with a dropdown list of the available > versions of documentation. If a user changes versions and the old version > does not have the current page, a notice will be displayed and the user > redirected to the home page for the desired version. > > This is a temporary measure to "catchup" the documentation for the website by > generating docs for all previous versions. Going forward, as each new > version of Mesos is released the documentation will be generated for that > version only. > >  > Screenshot of the dropdown list of versions. > >  > Screenshot of the message displayed if a page does not exist for the selected > version. > > > Diffs > ----- > > site/Gemfile 877fe914a9787c140848fdf9958571fec5fa58ff > site/Gemfile.lock 909f3f3badeaa47c80929e243ce36307766edee4 > site/Rakefile 31ef6ffe225ce7ddc573054058af1070b9e96b09 > site/config.rb 04bc7aa1e0ac61ce5d89fd53d32f265532996913 > site/data/releases.yml 56fd0fc7f5e34873c9b088778d77f9a6718a5933 > site/source/assets/js/versions.js PRE-CREATION > site/source/layouts/basic.erb 8a07488940f3793d6fdd291dbe896e098f321c96 > > > Diff: https://reviews.apache.org/r/52064/diff/7/ > > > Testing > ------- > > Testing was done manually to verify that the documentation was built for each > version of Mesos that is supported (some older versions do not have > compatible documentation). > > > Thanks, > > Tim Anderegg > >
