GitHub Pages Deployment & Case Sensitive Links

[PSchmiedmayer]

First of all, thanks for the excellent work with this package @helje5 ! Thanks for filling in the hole of

Deployment to GitHub Pages

As noted in your README, deploying the generated HTML pages to GitHub Pages within a GitHub Action would be a helpful addition. I have played around with this and created the following action to do so and wanted to share this with you: https://github.com/Apodini/Template-Repository/blob/feature/docCGitHubPages/.github/workflows/docs.yml
It uses xcodebuild to generate the documentation and your tool to generate a static HTML page that is then published to the gh-pages branch.

Feel free to reuse and share this GitHub Action if you find it useful.

Open Issues

The GitHub Action is part of the following pull request to add this to our template repo: Apodini/Template-Repository#8 .
While working on the PR, I found the following issues that I wanted to share with you:

1. GH Pages requires an index.html file at the root of the gh-pages branch. I have circumvented this by simply creating a basic HTML page in the GitHub Action that redirects to the index.html page found in the subfolders. It would probably be a nice addition to generate this directly using docc2html?
2. As noted in the comments of Try out GitHub pages and DocC Apodini/Template-Repository#8 there is an issue with the links between the different HTML pages. As the name of the type as well as the name of the target contains upper case characters, the links result in 404 errors. I think the solution would be to either make sure that all links between pages are only using lowercase characters or changing the folder structure to allow upper case characters as found in the Swift types, functions, etc. What do you think?

[helje5]

Wrt the index.html I was thinking that people may often want to have a custom introduction site. But I agree, would be nice to generate an overview page (or maybe copy the main package index to it, but adjusting the links). We should create an own issue to track this.

The thing with the links is likely more of a bug in DocC itself? 🤔 We could add an option to lowercase all links, but this is kinda wrong, because Swift source and symbols are case sensitive (i.e. you could have func doIt and func doIt in a single module). Again an own issue to track this would be nice.

I don't know that much about GH Actions. Should we host the action as part of this GH organisation? (it probably needs an own repository?)

[PSchmiedmayer]

@helje5 Thanks for the fast feedback and input! I will create separate issues for the two issues noted above so we can track them independently 👍

Regarding making a reusable GitHub Action out of the workflow presented above: Great idea. I can take a look at this over the next few days, and then we can host this as part of this organization.
It would make the very tailored approach that I took reusable across different repos. I already have some customizations options in mind.

[PSchmiedmayer]

@helje5 I have created two separate issues for the problems mentioned above. I have also updated the issues to highlight the problems with the GitHub Pages based deployment I use in the Apodini/Template-Repository repo.

In addition, I have created the first draft of a reusable GitHub Action that you can find in this repo: https://github.com/PSchmiedmayer/docc2html

I have successfully used the action in this GitHub Action run: https://github.com/Apodini/Template-Repository/runs/3415765546?check_suite_focus=true
The DocC documentation is successfully deployed to GitHub Pages: https://apodini.github.io/Template-Repository/documentation/apodinitemplate/apodinitemplate/index.html

The GitHub Action you have to put in your repo to use the action is just a few lines long: https://github.com/Apodini/Template-Repository/blob/feature/docCGitHubPages/.github/workflows/docs.yml

I am happy to move this action into a repo in this organization and add a README with some documentation.

[helje5]

Sorry for the delay, I added you to an org team. I can't find the setting which would allow you to create repos, so I guess I have to do that and then given you access. What would be a good name for the Action repository?

[PSchmiedmayer]

@helje5 Thanks a lot! I have accepted the invitation and will create a repo. What do you think about the name docc2ghpages for the GitHub Action and the respective repo?

[PSchmiedmayer]

@helje5 I have created a docc2ghpages GitHub Action as part of the DoccZz organization and have tagged a v1 release: https://github.com/DoccZz/docc2ghpages/releases/tag/v1.
The GitHub Action is used in this PR, and the repo demonstrates that it is working: Apodini/Template-Repository#8.

Therefore I am closing this issue. #14 and #15 contain detailed descriptions of the other issues I initially mentioned here. They still block Apodini/Template-Repository#8, but the GitHub pages deployment part is now working.