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

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

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