EDK2 doxygen documentation - adding docs for stable tags?

EDK2 doxygen documentation - adding docs for stable tags?

[Rebecca Cran]

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 doxygen documentation - adding docs for stable tags?

[Michael D Kinney]

Hi Rebecca,

Yes.  They are useful.  I would be better if it could be a CI job on either Azure pipelines
or GitHub Actions could run the tool and publish the documents in TianoCore.  Perhaps an on
demand job against a specific tag.

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-discuss] [edk2-devel] EDK2 doxygen documentation - adding docs for stable tags?

[Rebecca Cran]

How easy it is to push changes to https://www.tianocore.org/ ? I had 
thought that given how infrequently it's updated it's rather difficult, 
but I agree that's the ideal location for the Doxygen pages. If it's 
easier than I think, I have other changes I'd like to make such as 
updating https://www.tianocore.org/news/ which hasn't been changed since 
2018.


I agree it would be great if it could be a CI job somewhere: do we have 
any existing scheduled jobs in EDK2 already, or is it something that 
would need to be added?

Given that it was Stephano who originally said years ago that Doxygen 
generation should be in the cloud, and how nothing has changed since I'm 
skeptical about it, so for now I'll plan on setting up a scheduled job 
on my Gitlab instance (https://gitlab.bsdio.com) instead and continue 
publishing the pages on my site. But I'd be happy to help work towards 
putting it on tianocore.org as long as we don't lose any functionality 
in the process.


-- 
Rebecca Cran


On 11/9/21 7:27 PM, Michael D Kinney wrote:
> Hi Rebecca,
>
> Yes.  They are useful.  I would be better if it could be a CI job on either Azure pipelines
> or GitHub Actions could run the tool and publish the documents in TianoCore.  Perhaps an on
> demand job against a specific tag.
>
> 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 doxygen documentation - adding docs for stable tags?

[Michael D Kinney]

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 doxygen documentation - adding docs for stable tags?

[Rebecca Cran]

 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 doxygen documentation - adding docs for stable tags?

[Michael D Kinney]

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 doxygen documentation - adding docs for stable tags?

[Michael D Kinney]

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 doxygen documentation - adding docs for stable tags?

[Rebecca Cran]

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 doxygen documentation - adding docs for stable tags?

[Michael D Kinney]

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 doxygen documentation - adding docs for stable tags?

[Rebecca Cran]

I have a doxyfile at https://bsdio.com/edk2/docs/master.doxyfile which 
generates it.

I run "doxygen ../master.doxyfile" from the root of an edk2 clone.


-- 

Rebecca Cran


On 12/5/21 12:09 AM, Michael D Kinney wrote:
> 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 doxygen documentation - adding docs for stable tags?

[Rebecca Cran]

I have a doxyfile at https://bsdio.com/edk2/docs/master.doxyfile which 
generates it.

I run "doxygen ../master.doxyfile" from the root of an edk2 clone.


-- 

Rebecca Cran


On 12/5/21 12:09 AM, Michael D Kinney wrote:
> 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
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>
>>>>>
>>
>>
>>
>
>
> 
>
>