Re: [GIT PULL] doc: sphinx-4.8 DocBook to reST movement on Jon's docs-next

[Mauro Carvalho Chehab <mchehab@osg.samsung.com>]

Em Thu, 30 Jun 2016 11:25:11 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 29.06.2016 um 22:57 schrieb Mauro Carvalho Chehab <mchehab@osg.samsung.com>:
> 
> > Em Wed, 29 Jun 2016 11:52:09 -0600
> > Jonathan Corbet <corbet@lwn.net> escreveu:
> >   
> >>> 2. What is the best way to ship these migrations
> >>> 
> >>> or better I asked, what is your recommendation for a
> >>> migration strategy. Jani says, that this better belongs
> >>> to authors, but I have a doubt that we end with the
> >>> migration in the next years, if we wait about every author.
> >>> I think, supporting both infrastructures - the xml and the
> >>> reST - over a long period is not the best option. What is
> >>> your recommendation on this?    
> >> 
> >> I think we need to give maintainers the first shot at doing the conversion;
> >> in any case, I don't think we can just force it through without their
> >> cooperation.  And, honestly, while we're still groping around in this
> >> space, I think it's fine if we don't have lots of conversions right away.
> >> The ones that go more slowly will benefit from what we learn with the easy
> >> ones.
> >> 
> >> You could certainly talk to maintainers and see if they would like
> >> assistance with specific books.  Helping Mauro to get his tables done
> >> without going totally nuts would be a great first step, IMO.  
> > 
> > Yeah, going to each maintainer is the best way, as we're the ones
> > that will be bothered if something goes wrong on the documentation
> > (and code) that we maintain.  
> 
> Later if I have more time, may I will pick up those books who need
> only small correction e.g. "debugobjects" .. but when the time comes
> I will contact the maintainer and Jon' first.
> 
> > In the specific case of media stuff, the first step is to get the
> > flat-tree support and to put the migrated documentation on a separate
> > directory. Unfortunately, I have two sets of topic branches for 4.8,
> > and they both touch at the media docbook (and nothing prevents that
> > similar things to happen on 4.9 or any other version).
> > 
> > So, my plan is to keep both reST and docbook on Kernel for a while,
> > until be sure that everything is properly migrated.
> > 
> > Yet, I'm not sure if we should keep the migration scripts at the
> > Kernel tree, or if the best is to keep them in separate, as I
> > intend to not take more than one Kernel version to finish the
> > conversion. At least for media docbook, this will be a one-time
> > conversion.  
> 
> If I understood you right: the scripts, which are made the
> migration itself should not committed to the kernel tree (IMHO).
> Currently the scripts are available at my POC, may I could
> separate them into a python package which could be installed
> via python's pip. So if one wants to use this procedure of
> migration, he could install the package locally, make the
> conversion and after finishing, he uninstall the package. 

Sounds like a plan.

> 
> > So, I really appreciate if you could send me the patches with
> > the converted media documentation that you did. I'll merge it
> > after Jonathan applies the flat-tree patch on his tree, and
> > start reviewing and fixing the documentation over the main
> > branch.  
> 
> Yes, first flat-table to Jon', then the converted media book
> to Mauro, after this the man-page builder to Jon ... as long
> as there are no man-pages in media it should be smoothly.

OK.

> But I need a bit time, hopefully, end next week you got the
> media patch from me.

Ok, but please notice that the end of the next week is probably too late
for 4.8. Next week, we'll be on -rc6, and most maintainers freeze their
trees during -rc7, except for bug fixes. Ok, as this is just documentation
and should not cause regressions, I may open an exception, if it won't
cause any troubles to Jon.

> 
> -- Markus --
> 
> > I'll need to track the topic branch changes at the
> > Docbook, to apply them again at the master tree, once they
> > gets merged during the 4.8 window. Thankfully, there aren't
> > complex elements on such changes (as far as I remember).
> > 
> > If everything goes right, by -rc2 or -rc3 I'll likely be dropping
> > the DocBook/media from my tree.
> > 
> > --  
> > Thanks,
> > Mauro  
> 


-- 
Thanks,
Mauro