How to provide online access to source documentation upon release.

[Fran-B]

🏷️ Discussion Type

Question

Body

As I see it, the release of a code library contains at least the following files:

• The built library object.
• The documentation (in HTML) for the library content as generated by appropriate tool (probable zipped together).
• Release notes.

What I would like is for the repository to contain a link to the generated documentation from the latest release. Preferably in the side menu when viewing the repo.

One method would be for me to publish that documentation on some external web site. Then I suppose that I could provide a link to that index in the README.md file.

I know that "pages" exist and would provide the desired link, but it seems to me that may have the following issues:

1. It would require that all the documentation files/directories be committed into the repository itself.
2. Each release would then require removal of all documentation files and directories, except index.html, and replacement with the new set that may have any number of files changed, removed or renamed.
3. Users pulling the repo would then get all those files when it would be more appropriate for them to generate them.
4. Finally, I wonder if the relatively-referenced HTML files will actually display properly in a browser. When I linked a "index.html" into a README.md file I got the "code" file rather than an actual rendering of the HTML itself.

I apologize if something like this has already been asked. The few questions that my search turned up cause me more confision that help.

[Carloscavalcante3]

If I understand correctly, you're looking for a way to make the latest generated HTML documentation available from your repository without cluttering the main branch with generated files or forcing users to download them.

GitHub Pages is actually intended for this use case. You don't need to commit the generated documentation to your main branch. Instead, you can publish it to a dedicated gh-pages branch (or via the Pages deployment workflow), while keeping your source code separate.

This also addresses your concern about replacing documentation files on every release—the deployment simply publishes the newly generated documentation, so there's no need to manually manage those files in your main branch.

As for the HTML rendering, the reason your index.html was displayed as source code is that files viewed directly in a repository are served as file contents. When the same files are served through GitHub Pages, they are rendered as a website, so relative links between HTML files, CSS, JavaScript, and images work as expected.

Hope that helps!

[Fran-B]

Okay, yes you seem to understand my needs and concerns correctly.
However, although I understand what you mean by publishing it from a gh-pages branch, I am curious what you mean by "or via the Pages deployment workflow"?
Are you saying that I can skip the branch altogether and release it from some sort of workflow process?
I am very new to GitHub and have yet to create a release. Are saying that I can update the "published pages" as part of my release process?
I would very much like to understand what you mean by that.

[Carloscavalcante3]

Exactly, GitHub Pages has two publishing methods:

1. From a branch (traditionally gh-pages), where the generated HTML files are stored in that branch.
2. From a GitHub Actions workflow, where the documentation is generated during the workflow and then deployed directly to GitHub Pages. With this approach, you don't have to maintain a gh-pages branch yourself—the workflow builds the documentation and publishes it for you.

Since you're new to GitHub, I'd actually recommend starting with the first option because it's easier to understand. Once you're comfortable with GitHub Actions, you can automate the entire process.

And yes, you can absolutely make this part of your release process. For example, when you create a new release (or push a version tag), a GitHub Actions workflow can:

• build your library,
• generate the HTML documentation,
• create the release assets, and
• publish the updated documentation to GitHub Pages.

That way, every release automatically updates the documentation website, and your main branch stays free of generated files.

[Fran-B]

Thank you very mush for all this informaiton.

[jeman-arcanist]

The best practice is not to commit generated HTML documentation into your main source branch.

Instead, use GitHub Pages with an automated workflow:

• Generate the documentation during your release process (e.g., with Doxygen, Sphinx, Javadoc, etc.).

• Use a GitHub Actions workflow to publish the generated HTML to GitHub Pages.

• The documentation is hosted separately from your source code, so developers cloning the repository don't download generated files.

• You can add the Pages URL to:

  • the repository description,
  • the README,
  • or the repository's Website field so it appears in the repository sidebar.

This avoids all of the concerns you listed:

• ✅ No generated HTML committed to your source branch.
• ✅ No manual deletion/replacement of documentation files every release.
• ✅ Documentation updates automatically with each release or push.
• ✅ HTML is served as a website, so relative links work correctly. Opening index.html from the repository itself shows the source, because GitHub serves repository files as text rather than rendering them as web pages.

If you want documentation tied to each release, another common approach is:

• Publish the latest docs on GitHub Pages.
• Attach a ZIP of the generated documentation as a release asset for each tagged release, so users can download the docs that match a specific version.

Overall, the typical setup is:

Source code
      │
      ▼
GitHub Actions
      │
Generate HTML docs
      │
      ├── Deploy latest → GitHub Pages
      └── Attach docs.zip → GitHub Release

This is the approach used by many open-source projects because it keeps the repository clean while still providing browsable, versioned documentation.