On Thu, 16 Apr 2020, Nicolas Dechesne wrote:

>
>
> On Thu, Apr 16, 2020 at 7:46 PM Robert P. J. Day <rpjday@crashcourse.ca> wrote:
>       On Thu, 16 Apr 2020, Nicolas Dechesne wrote:
>
>       > As I put in one of my emails before you can use my dev branch:
>       >
>       > https://git.linaro.org/people/nicolas.dechesne/poky.git/log/?h=sphinx
>       >
>       > then it's just
>       > pip3 install sphinx
>       > # to use the non default theme
>       > pip3 install sphinx_rtd_theme
>       >
>       > cd documentation make html
>       >
>       > and it should generate exactly that on your local folder
>       > https://people.linaro.org/~nicolas.dechesne/yp-docs/
>       >
>       > I am happy to take patches in this branch (or create/maintain a
>       > contrib branch if more folks want to play/experiment and send
>       > patches).
>
>         definitely need some mechanism to handle docbook entities and basic
>       tags like <filename> ... i'm still poring over pandoc, can it be
>       configured to deal with that?
>
>         will go read more ...
>
>
> It does 'most of the time'. See:
> https://people.linaro.org/~nicolas.dechesne/yp-docs/bsp-guide/bsp.xml.html#bsp-layers
>
> where the docbook source is:
>        Each repository is a BSP layer supported by the Yocto Project                                  
>                                                                                                      
>                          
>         (e.g. <filename>meta-raspberrypi</filename> and                                              
>                                                                                                      
>                            
>         <filename>meta-intel</filename>).                                                            
>                                                                                                      
>                            
>  I am not sure if it always does the *right* thing though.. and I
> have seen occurrences where it failed. I am wondering if we should
> 'fix' pandoc , or just spend some time fixing the output of pandoc.
> I don't think we will avoid reading/checking each manual, anyways..
> I was thinking we could use pandoc for 80% of the work, some regex
> for 15% and then manually finish the work.. it might be a bit
> optimistic ;)

  interesting ... if you go to the top-level page:

https://people.linaro.org/~nicolas.dechesne/yp-docs/bsp-guide/bsp-guide.xml.html

the <filename> tag in the third note is *not* migrated over, you can
still see the tag. i suspect there will be plenty of tweaking, but i'm
still totally on-board with this, and am willing to contribute.

rday