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


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






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






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





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








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








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






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









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









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