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

["Michael D Kinney" <michael.d.kinney@intel.com>]

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
> > >>
> > >>
> > >>
> > >>
> > >>
> > >>
> >
> >
> > 
> >