On Fri, Mar 8, 2013 at 7:32 PM, Anne Gentle <[email protected]> wrote:
> > > > On Fri, Mar 8, 2013 at 3:38 PM, Laura Alves <[email protected]> wrote: > >> >> >> On Fri, Mar 8, 2013 at 4:50 PM, Jeremy Stanley <[email protected]> wrote: >> >>> I'm Cc'ing you to be on the safe side because I'm unsure whether >>> you're subscribed to the list. Forgive me for the duplicate reply if >>> you are! >>> >>> No problem, thanks! I'm, but I forgot to add Anne. Sorry! >> >> > > Thanks for looping me in! > > >> On 2013-03-08 00:01:46 -0300 (-0300), Laura Alves wrote: >>> [...] >>> > Currently, the API samples we use to document are the ones added >>> > by developers to their respective repo doc folders (commonly >>> > 'repo'/doc/api_samples/'api_name'. So what we're doing when >>> > documenting a new API (or updating the samples of an existing one) >>> > is basically downloading the new files and adding them to our >>> > commit, so then they are merged to the API-site repo. Certainly >>> > having the files copied from one repo to another this way is a big >>> > part of the work, and not a super-fun one. >>> [...] >>> >>> Would it be possible for the API doc jobs to just retrieve an >>> up-to-date git clone of whatever project/branch they're documenting >>> at build time? Or would it maybe make more sense to merge the API >>> documentation into the projects they're documenting and simply >>> generate updated API documentation as a publish job out of the post >>> queue for each commit? I mainly just want to make sure that we're >>> not simply codifying a particular human workflow which might not >>> actually be well suited to automation. >>> >>> > I think that an automation of a git clone would work. There may be one > additional automation that would help achieve the end-goal. > > The blueprint/discussion for this is here: > https://blueprints.launchpad.net/openstack-manuals/+spec/api-samples-to-api-site > > The main idea is to ensure the most updated samples are available to the > docs site. I think the workflow should be: > > 1. A nova dev makes new template files for API samples, checks into nova > repo. > 2. Devs do the review process on nova repo, approve the patch. > 3. At merge time, api_samples are built from templates (I don't believe > this is automated currently, Sean Dague has to remind nova devs to make > sure samples are built, possibly this could happen prior to approval). > 4. At merge time, git clone the api_samples directory to the api-site repo > into the correct directory. > > Seem like a good workflow or too much robot? > > Anne > > > >> If there are technical or policy reasons to have these files >>> duplicated but kept in sync between projects, then it may be >>> possible to make a job triggered from merges to one project >>> automatically propose changes to another. That definitely sounds >>> hacky to me, though, if it can be avoided at all through >>> reorganization of those projects to avoid that duplication in the >>> first place. >>> >>> >> I agree, I don't want to automatize this more than necessary or >> recommended. My main concern is to get these new samples available to the >> api-site repo in the most lightweight and less troubling way, even if it's >> a one-time solution, at least for now. >> >> I wouldn't have any problems with coping and checking the current samples >> myself, but I'd still like to see if there is a possible solution for the >> upcoming samples by reorganizing / improving some processes, even if it's >> not on the infra side (you still have a better view of the big picture). >> I'm really not a fan of duplicating stuff neither, but I personally like >> less the idea of merging repos with samples which have not been checked for >> consistency by the doc team. >> >> > I thought outlining this through email would be better to reach >>> > everyone despite the time zones, but I'll be totally available to >>> > continue the discussion in the infra channel (I won't be this >>> > sleepy, hopefully). >>> >>> Yes, the easiest times to reach the bulk of our Infra core >>> developers on IRC tend to be between 1700-0300 UTC on weekdays, but >>> we're often around at other times as well (I tend to be on starting >>> at about 1300 UTC for example). >>> >>> Cool, I'm not sure that what I've said makes any sense at this point, so >> I'll be bothering over there too :D >> >> Thanks! >> ladquin >> >> >>> -- >>> Jeremy Stanley >>> >> >> > Today with Anne we discussed also the possibility of going the other way around with the API site: instead of moving the samples to our doc repo, we'd move our wadl's, xml's and any other needed files to each API project repo, and then we'd have "one-page-per-api" instead of the long, growing one we have now. >From the Jenkins side, it shouldn't be a problem (I think), it would required as many jobs as API pages we need to publish. I like this approach for some reasons: - It's one step forward to some level of automation regarding API publishing. - It will be "cleaner" in from the repo/jenkins' jobs point of view: no hacky or duplicated stuff. - The API catalog is growing constantly, the page is getting bulky, splitting it up may allow some aesthetic / maintaining improvements. There are some other issues we're still to find out / discuss: - Devs will have to review/approve API doc patches. Doc'ers (!) may need to approve their new API samples (not sure about this). - It is more work than the original idea (though, if it works, the benefits in the long run will be bigger) - Some other technical point that has just left my mind (Sorry, I shouldn't write emails after midnight). As usual, comments, questions and corrections are welcome! Thanks! ladquin
_______________________________________________ OpenStack-Infra mailing list [email protected] http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-infra
