Convert docs from Sphinx to Hugo

[jaylinski]

Description

This PR converts the docs from Sphinx to Hugo (https://gohugo.io/).
The Sphinx build was broken for some time now (#1225) and the issue
is obviously not easy to track down. I chose Hugo because it has the advantage
of only needing a single binary, which makes building the docs very easy.

In order to build and publish the docs, a GitHub Action
was added. This action pushes the docs to the gh-pages
branch so it can be served by GitHub Pages. An example
can be viewed here: https://github.com/jaylinski/phpspec/runs/431772750

The file-format was changed from rst to markdown (converted with pandoc), because it is a format most devs are familiar with.

A preview of the converted docs can be viewed here: https://jaylinski.github.io/phpspec/

Follow up from #1296.

What implications does this change have?

Positive effects

• The docs website is now ten times smaller and three times faster:
  New: 5 requests / 28.90 KB / 25.88 KB transferred / Finish: 459 ms / DOMContentLoaded: 182 ms / load: 460 ms
  Old: 31 requests / 435.32 kB / 258.37 kB transferred / Finish: 1.84 s / DOMContentLoaded: 828 ms / load: 1.56 s
• The docs website is now responsive (mobile-first)
• Build is super fast (210 ms for Hugo build, 24 seconds for complete pipeline)
• 3,108 additions and 6,836 deletions (less code for same result)
• Adds an "Improve this page" button to the end of the docs
• Closes Docs build is failing #1225

Downsides

• No more version selector
• No more readthedocs analytics
• No fancy icons on code highlighting boxes
• Menu item "phpspec manual" is not shown as active when a cookbook page is viewed (works only for pages in "manual" folder)
• No in-site search (you have to use DuckDuckGo or Google)
• Links are changing (although Hugo supports aliases/redirects)

What do I as a maintainer have to do to get this to work?

1. Merge this PR
2. Point the phpspec.net URL to the GitHub page

An alternative is deploying the docs to Netlify, which has the benefit of getting a free https certificate for the domain.

What was my motivation to do this?

I wanted to try out GitHub Actions and saw this as a fitting opportunity. In hindsight I should have probably picked a static site generator specifically made for documentation, like GitBook, VuePress, Sculpin or some in https://github.com/myles/awesome-static-generators#documentation.

[ciaranmcnulty]

Thanks for all this work

Readthedocs.io has the ability to serve different versions of the documentation with a version picker - is this something we could reproduce? If not, maybe we should think about merging the docs into the latest (we haven't deprecated much over the years)

[stof]

which has the benefit of getting a free https certificate for the domain.

github pages also do that (and readthedocs.io can also do it with the right DNS config)

[jaylinski]

@ciaranmcnulty Yes, this is (somewhat) possible. See jaegertracing/documentation#79. Kubernetes is also using Hugo (https://github.com/kubernetes/website/blob/master/config.toml).

I'll try to add a version-picker this week.

[jaylinski]

Readthedocs.io has the ability to serve different versions of the documentation with a version picker - is this something we could reproduce? If not, maybe we should think about merging the docs into the latest (we haven't deprecated much over the years)

@ciaranmcnulty I added a simple version picker. Can be viewed here: https://jaylinski.github.io/phpspec/v7/manual/introduction/

This works by having a folder for each major release and is similar to how jaegertracing (https://github.com/jaegertracing/documentation) handle their Hugo docs.

It would probably make sense to also create a "next" version, which can later be "released" as v8.

[ciaranmcnulty]

@jaylinski what steps would be needed to deploy this onto GitHub pages, on a subdomain of phpspec.net for testing?

[jaylinski]

@ciaranmcnulty

1. Merge this PR (I would change the target branch to something other than main for testing purposes, like docs.)
   • If you change the branch, you also have to change branch in the file .github/workflows/docs.yml:

   on:
       push:
           branches:
               - docs
   

2. Change the baseUrl in docs/config.toml to "https://phpspec.github.io/phpspec/" or a subdomain of your choice and push it to the merged docs branch
3. The docs should be automatically be built and pushed to the gh-pages-branch
4. Make sure GitHub Pages is active (https://github.com/phpspec/phpspec/settings)
   • Here you can also add a sub-domain of your choice
5. You should now be able to view the docs. Visit https://phpspec.github.io/phpspec/ or your custom subdomain.

[jaylinski]

@ciaranmcnulty If you need more information, feel free to ask.

If you don't want to go with Hugo: an alternative would be to use the markdown-files I already converted and publish those with GitBook or something similar.

[ciaranmcnulty]

Not abandoning, just no time to look at it lately :/

If someone can set up a mirror that's totally working just under another domain name that'd make it an easy merge :)

[jaylinski]

If someone can set up a mirror that's totally working just under another domain name that'd make it an easy merge

@ciaranmcnulty My mirror is here: https://jaylinski.github.io/phpspec/

If you want it under https://phpspec.github.io/phpspec/, I will change the domain in the Hugo config. After that, all you have to do is activate GitHub pages in https://github.com/phpspec/phpspec/settings and merge the PR.

If you want, you can give me temporary maintainer permissions and I'll set it up. :)

[jaylinski]

Since 6 months have passed since my last comment, I wanted to check in with you.

Would be nice to get this merged and published so developers could have an up-to-date documentation.

[jaylinski]

Since another 6 months have passed since my last comment, I wanted to check in with you.

Would be nice to get this merged and published so developers could have an up-to-date documentation.