Re: [edI k2-devel] EDK2 doxygen documentation - adding docs for stable tags?

Re: [edI k2-devel] EDK2 doxygen documentation - adding docs for stable tags?

[Michael D Kinney]

Rebecca,

I am guessing that you just ran Doxygen against the tree without the 
processing of DEC files that provides the LibraryClass, Protocol, PPI, GUID
and PCD information from each package.

These are the extra pages that the PackageDocumentTools produce.

So a combined version with those extra pages per package with global
search would be very good.

I was thinking that the external tag files with a top level project
that linked everything together may be a way to get there.  The
simple top level index.html was just a quick way to get something 
working with GitHub pages.

Mike

> -----Original Message-----
> From: Kinney, Michael D <michael.d.kinney@intel.com>
> Sent: Saturday, December 4, 2021 11:09 PM
> To: devel@edk2.groups.io; rebecca@bsdio.com; Kinney, Michael D <michael.d.kinney@intel.com>
> Subject: RE: [edk2-devel] EDK2 doxygen documentation - adding docs for stable tags?
> 
> Rebecca,
> 
> I like that combined version.
> 
> How did you package them together?
> 
> Mike
> 
> > -----Original Message-----
> > From: devel@edk2.groups.io <devel@edk2.groups.io> On Behalf Of Rebecca Cran
> > Sent: Saturday, December 4, 2021 8:31 PM
> > To: Kinney, Michael D <michael.d.kinney@intel.com>; devel@edk2.groups.io
> > Subject: Re: [edk2-devel] EDK2 doxygen documentation - adding docs for stable tags?
> >
> > Thanks. Would it be possible to have all the packages together, like
> > https://bsdio.com/edk2/docs/master/index.html (ignoring that the page
> > has information about Dynamic AML Generation!)?
> >
> >
> > I'm not sure if we need to include the cross-referenced source files
> > like mine does, but it might be nice.
> >
> >
> > --
> > Rebecca Cran
> >
> >
> > On 12/4/21 21:01, Kinney, Michael D wrote:
> > > Hi Rebecca,
> > >
> > > Here is a first pass at publishing all the package documents on GitHub Pages.
> > >
> > > 	https://mdkinney.github.io/edk2/index.html
> > >
> > > I have a GitHub Action that pulls the code from an edk2 repo for a specific
> > > branch/tag/sha, installs doxygen, generates the HTML documentation for
> > > all packages, and publishes the HTML content to a gh-pages branch.  GitHub
> > > deploys a new version of the web pages each time there is a push to the
> > > gh-pages branch.
> > >
> > > I had to make a couple small fixes to PackageDocumentTools.  I will enter
> > > a BZ and get those reviewed. The branch with those fixes are here:
> > >
> > >      https://github.com/mdkinney/edk2/tree/Bug_xxx_PackageDocumentationToolFixes
> > >      https://github.com/mdkinney/edk2/commit/e3eb394ea52621dc02e45d4f78f319cfeb0da68f
> > >
> > > The GitHub Action is located here:
> > >
> > >      https://github.com/mdkinney/edk2/blob/sandbox/CompareBuild/.github/workflows/PackageDocumentationBuild.yml
> > >
> > > The deployments page is here.  It is updates each time new content is pushed
> > > to gh-pages branch.
> > >
> > >      https://github.com/mdkinney/edk2/deployments/activity_log?environment=github-pages
> > >
> > > This first attempt pushes to a gh-pages branch in my personal fork of the edk2 repo.
> > > Given the size of the HTML documentation, I would not recommend that this content be
> > > stored in the same repo with the edk2 sources.  I would recommend creating a new
> > > repo in the tianocore-docs org that would host the GitHub action and can fetch a
> > > branch/tag/sha from tianocore/edk2 to publish package documentation in the
> > > tianocore-docs org repository.
> > >
> > > Please review the results and compare to your previous work to see if this is
> > > an equivalent replacement.
> > >
> > > The GitBook documents that are also hosted in tianocore-docs org support publishing
> > > multiple releases and a draft release of each document by adding a top level
> > > directory to gh-pages.  We could do the same for package documentation by
> > > having a weekly publication of the draft based on latest tianocore/edk2/master.
> > > And we could generate a released version of the package documentation
> > > when a new stable-tag is added to tianocore/edk2.
> > >
> > > Thanks,
> > >
> > > Mike
> > >
> > >> -----Original Message-----
> > >> From: Kinney, Michael D <michael.d.kinney@intel.com>
> > >> Sent: Wednesday, December 1, 2021 9:02 AM
> > >> To: devel@edk2.groups.io; rebecca@bsdio.com; Kinney, Michael D <michael.d.kinney@intel.com>
> > >> Subject: RE: [edk2-devel] EDK2 doxygen documentation - adding docs for stable tags?
> > >>
> > >> Hi Rebecca,
> > >>
> > >> It does not push to gitbook server.  It is pushed to web pages hosted by GitHub.
> > >>
> > >> It uses gitbook tools to process MD files into published PDF, MOBI, HTML.
> > >>
> > >> For example, the EDK II Build Specification has repo in GitHub:
> > >>
> > >>      https://github.com/tianocore-docs/edk2-BuildSpecification
> > >>
> > >> And the HTML version of the draft revision of this spec is published here:
> > >>
> > >>      https://tianocore-docs.github.io/edk2-BuildSpecification/draft/
> > >>
> > >> These are the web pages associated with tianocore-docs org.
> > >>
> > >> Thanks,
> > >>
> > >> Mike
> > >>
> > >>> -----Original Message-----
> > >>> From: devel@edk2.groups.io <devel@edk2.groups.io> On Behalf Of Rebecca Cran
> > >>> Sent: Wednesday, December 1, 2021 8:52 AM
> > >>> To: Kinney, Michael D <michael.d.kinney@intel.com>; devel@edk2.groups.io
> > >>> Subject: Re: [edk2-devel] EDK2 doxygen documentation - adding docs for stable tags?
> > >>>
> > >>>   From what I can see, the tianocore-docs actions push to gitbooks, not
> > >>> tianocore.org?
> > >>>
> > >>> I don't think gitbooks will work for the doxygen pages.
> > >>>
> > >>>
> > >>> --
> > >>>
> > >>> Rebecca Cran
> > >>>
> > >>>
> > >>> On 11/30/21 20:21, Kinney, Michael D wrote:
> > >>>> Hi Rebecca,
> > >>>>
> > >>>> This is a good idea.  We use GitHub Actions to publish the EDK II Specifications
> > >>>> to a web page hosted as part of the documents GitHub repo.
> > >>>>
> > >>>> I think we can do something similar for generating and publishing the doxygen
> > >>>> generated web content for the edk2 packages.  I think a manually triggered
> > >>>> GitHub action in a repo in tianocore-docs organization might be a good place
> > >>>> to do this so all document publication activities are under that same org.
> > >>>> The GitHub action can take a branch or tag or sha of the edk2 repo as input
> > >>>> to generate the doxygen documentation.
> > >>>>
> > >>>> Best regards,
> > >>>>
> > >>>> Mike
> > >>>>
> > >>>>> -----Original Message-----
> > >>>>> From: devel@edk2.groups.io <devel@edk2.groups.io> On Behalf Of Rebecca Cran
> > >>>>> Sent: Tuesday, November 9, 2021 3:20 PM
> > >>>>> To: devel@edk2.groups.io; discuss@edk2.groups.io
> > >>>>> Subject: [edk2-devel] EDK2 doxygen documentation - adding docs for stable tags?
> > >>>>>
> > >>>>> I've been hosting the Doxygen documentation for EDK2 at
> > >>>>> https://bsdio.com/edk2/docs for a few years now. I previously had
> > >>>>> versions for master, UDK2015, UDK2017, UDK2018 etc. but since migrating
> > >>>>> my web server dropped everything except master.
> > >>>>>
> > >>>>>
> > >>>>> I was wondering if people are finding it useful, and if so whether
> > >>>>> they'd like me to generate documentation for each stable tag too?
> > >>>>>
> > >>>>>
> > >>>>> Personally, _I_ find the web-based version (as opposed to a
> > >>>>> locally-generated version) useful for the search feature -- being able
> > >>>>> to quickly find the documentation for a certain function.
> > >>>>>
> > >>>>>
> > >>>>> --
> > >>>>>
> > >>>>> Rebecca Cran
> > >>>>>
> > >>>>>
> > >>>>>
> > >>>>>
> > >>>>>
> > >>>>>
> > >>>
> > >>>
> > >>>
> >
> >
> > 
> >

Re: [edk2-devel] [edk2-devel] EDK2 doxygen documentation - adding docs for stable tags?

[Rebecca Cran]

Exactly. That sounds good.


--

Rebecca Cran

On 12/5/21 12:23 AM, Michael D Kinney wrote:
> Rebecca,
>
> I am guessing that you just ran Doxygen against the tree without the
> processing of DEC files that provides the LibraryClass, Protocol, PPI, GUID
> and PCD information from each package.
>
> These are the extra pages that the PackageDocumentTools produce.
>
> So a combined version with those extra pages per package with global
> search would be very good.
>
> I was thinking that the external tag files with a top level project
> that linked everything together may be a way to get there.  The
> simple top level index.html was just a quick way to get something
> working with GitHub pages.
>
> Mike
>
>> -----Original Message-----
>> From: Kinney, Michael D <michael.d.kinney@intel.com>
>> Sent: Saturday, December 4, 2021 11:09 PM
>> To: devel@edk2.groups.io; rebecca@bsdio.com; Kinney, Michael D <michael.d.kinney@intel.com>
>> Subject: RE: [edk2-devel] EDK2 doxygen documentation - adding docs for stable tags?
>>
>> Rebecca,
>>
>> I like that combined version.
>>
>> How did you package them together?
>>
>> Mike
>>
>>> -----Original Message-----
>>> From: devel@edk2.groups.io <devel@edk2.groups.io> On Behalf Of Rebecca Cran
>>> Sent: Saturday, December 4, 2021 8:31 PM
>>> To: Kinney, Michael D <michael.d.kinney@intel.com>; devel@edk2.groups.io
>>> Subject: Re: [edk2-devel] EDK2 doxygen documentation - adding docs for stable tags?
>>>
>>> Thanks. Would it be possible to have all the packages together, like
>>> https://bsdio.com/edk2/docs/master/index.html (ignoring that the page
>>> has information about Dynamic AML Generation!)?
>>>
>>>
>>> I'm not sure if we need to include the cross-referenced source files
>>> like mine does, but it might be nice.
>>>
>>>
>>> --
>>> Rebecca Cran
>>>
>>>
>>> On 12/4/21 21:01, Kinney, Michael D wrote:
>>>> Hi Rebecca,
>>>>
>>>> Here is a first pass at publishing all the package documents on GitHub Pages.
>>>>
>>>> 	https://mdkinney.github.io/edk2/index.html
>>>>
>>>> I have a GitHub Action that pulls the code from an edk2 repo for a specific
>>>> branch/tag/sha, installs doxygen, generates the HTML documentation for
>>>> all packages, and publishes the HTML content to a gh-pages branch.  GitHub
>>>> deploys a new version of the web pages each time there is a push to the
>>>> gh-pages branch.
>>>>
>>>> I had to make a couple small fixes to PackageDocumentTools.  I will enter
>>>> a BZ and get those reviewed. The branch with those fixes are here:
>>>>
>>>>       https://github.com/mdkinney/edk2/tree/Bug_xxx_PackageDocumentationToolFixes
>>>>       https://github.com/mdkinney/edk2/commit/e3eb394ea52621dc02e45d4f78f319cfeb0da68f
>>>>
>>>> The GitHub Action is located here:
>>>>
>>>>       https://github.com/mdkinney/edk2/blob/sandbox/CompareBuild/.github/workflows/PackageDocumentationBuild.yml
>>>>
>>>> The deployments page is here.  It is updates each time new content is pushed
>>>> to gh-pages branch.
>>>>
>>>>       https://github.com/mdkinney/edk2/deployments/activity_log?environment=github-pages
>>>>
>>>> This first attempt pushes to a gh-pages branch in my personal fork of the edk2 repo.
>>>> Given the size of the HTML documentation, I would not recommend that this content be
>>>> stored in the same repo with the edk2 sources.  I would recommend creating a new
>>>> repo in the tianocore-docs org that would host the GitHub action and can fetch a
>>>> branch/tag/sha from tianocore/edk2 to publish package documentation in the
>>>> tianocore-docs org repository.
>>>>
>>>> Please review the results and compare to your previous work to see if this is
>>>> an equivalent replacement.
>>>>
>>>> The GitBook documents that are also hosted in tianocore-docs org support publishing
>>>> multiple releases and a draft release of each document by adding a top level
>>>> directory to gh-pages.  We could do the same for package documentation by
>>>> having a weekly publication of the draft based on latest tianocore/edk2/master.
>>>> And we could generate a released version of the package documentation
>>>> when a new stable-tag is added to tianocore/edk2.
>>>>
>>>> Thanks,
>>>>
>>>> Mike
>>>>
>>>>> -----Original Message-----
>>>>> From: Kinney, Michael D <michael.d.kinney@intel.com>
>>>>> Sent: Wednesday, December 1, 2021 9:02 AM
>>>>> To: devel@edk2.groups.io; rebecca@bsdio.com; Kinney, Michael D <michael.d.kinney@intel.com>
>>>>> Subject: RE: [edk2-devel] EDK2 doxygen documentation - adding docs for stable tags?
>>>>>
>>>>> Hi Rebecca,
>>>>>
>>>>> It does not push to gitbook server.  It is pushed to web pages hosted by GitHub.
>>>>>
>>>>> It uses gitbook tools to process MD files into published PDF, MOBI, HTML.
>>>>>
>>>>> For example, the EDK II Build Specification has repo in GitHub:
>>>>>
>>>>>       https://github.com/tianocore-docs/edk2-BuildSpecification
>>>>>
>>>>> And the HTML version of the draft revision of this spec is published here:
>>>>>
>>>>>       https://tianocore-docs.github.io/edk2-BuildSpecification/draft/
>>>>>
>>>>> These are the web pages associated with tianocore-docs org.
>>>>>
>>>>> Thanks,
>>>>>
>>>>> Mike
>>>>>
>>>>>> -----Original Message-----
>>>>>> From: devel@edk2.groups.io <devel@edk2.groups.io> On Behalf Of Rebecca Cran
>>>>>> Sent: Wednesday, December 1, 2021 8:52 AM
>>>>>> To: Kinney, Michael D <michael.d.kinney@intel.com>; devel@edk2.groups.io
>>>>>> Subject: Re: [edk2-devel] EDK2 doxygen documentation - adding docs for stable tags?
>>>>>>
>>>>>>    From what I can see, the tianocore-docs actions push to gitbooks, not
>>>>>> tianocore.org?
>>>>>>
>>>>>> I don't think gitbooks will work for the doxygen pages.
>>>>>>
>>>>>>
>>>>>> --
>>>>>>
>>>>>> Rebecca Cran
>>>>>>
>>>>>>
>>>>>> On 11/30/21 20:21, Kinney, Michael D wrote:
>>>>>>> Hi Rebecca,
>>>>>>>
>>>>>>> This is a good idea.  We use GitHub Actions to publish the EDK II Specifications
>>>>>>> to a web page hosted as part of the documents GitHub repo.
>>>>>>>
>>>>>>> I think we can do something similar for generating and publishing the doxygen
>>>>>>> generated web content for the edk2 packages.  I think a manually triggered
>>>>>>> GitHub action in a repo in tianocore-docs organization might be a good place
>>>>>>> to do this so all document publication activities are under that same org.
>>>>>>> The GitHub action can take a branch or tag or sha of the edk2 repo as input
>>>>>>> to generate the doxygen documentation.
>>>>>>>
>>>>>>> Best regards,
>>>>>>>
>>>>>>> Mike
>>>>>>>
>>>>>>>> -----Original Message-----
>>>>>>>> From: devel@edk2.groups.io <devel@edk2.groups.io> On Behalf Of Rebecca Cran
>>>>>>>> Sent: Tuesday, November 9, 2021 3:20 PM
>>>>>>>> To: devel@edk2.groups.io; discuss@edk2.groups.io
>>>>>>>> Subject: [edk2-devel] EDK2 doxygen documentation - adding docs for stable tags?
>>>>>>>>
>>>>>>>> I've been hosting the Doxygen documentation for EDK2 at
>>>>>>>> https://bsdio.com/edk2/docs for a few years now. I previously had
>>>>>>>> versions for master, UDK2015, UDK2017, UDK2018 etc. but since migrating
>>>>>>>> my web server dropped everything except master.
>>>>>>>>
>>>>>>>>
>>>>>>>> I was wondering if people are finding it useful, and if so whether
>>>>>>>> they'd like me to generate documentation for each stable tag too?
>>>>>>>>
>>>>>>>>
>>>>>>>> Personally, _I_ find the web-based version (as opposed to a
>>>>>>>> locally-generated version) useful for the search feature -- being able
>>>>>>>> to quickly find the documentation for a certain function.
>>>>>>>>
>>>>>>>>
>>>>>>>> --
>>>>>>>>
>>>>>>>> Rebecca Cran
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>
>>>>>>
>>>
>>>
>>>
>
>
> 
>
>