[WIP] Autogenerated documentation site

[johnmccabe]

Signed-off-by: John McCabe [email protected]

Description

Raising a WIP PR for the autogeneration of the documentation site. This includes both the autogeneration of the site, and also some moving, restructuring and updates to the current content in order to make the resulting site flow more cleanly and to fill out gaps/remote redundancy and repetition (the bit that involves work).

The current implementation goes with mkdocs with the material theme, with a custom monochrome logo, some light styling to the logo css and custom colour to match the openfaas.com site.

The WIP site is being deployed from the PR branch from my fork via Travis, it can be seen here:

• https://johnmccabe.github.io/faas/

Motivation and Context

• I have raised an issue to propose this change (Hacktoberfest: generated documentation site #253)

How Has This Been Tested?

Testing for this is pending, we'll likely need the following

• Proof read by @alexellis for feedback on structure/content
• Autogeneration of docs from a fork to a custom domain

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I've read the CONTRIBUTION guide
• I have signed-off my commits with git commit -s
• I have added tests to cover my changes.
• All new and existing tests passed.

[open-derek]

Thank you for your contribution. I've just checked and your commit doesn't appear to be signed-off.
That's something we need before your Pull Request can be merged. Please see our contributing guide.

[alexellis]

Pushing up WIP early, DO NOT MERGE
?

[alexellis]

Hi John, the template for this looks really good and it's really useful to have the Travis instructions or building the site, too.

I'm thinking of the documentation sitting in its own repository so it is self-contained.

I'm not sure if I've seen the roadmap etc brought into a docs site. I'll check what Docker and Kubernetes are doing who I know are an inspiration for our project.

[ericstoekl]

@alexellis I've taken these changes and merged them to the latest commit in master here:

https://github.com/ericstoekl/faas/tree/markdown-docs

Should we create a new PR for this? What still needs to be done for this PR?

[alexellis]

@johnmccabe didn't sign all the commits off for this documentation site. Also the docs have progressed since this PR was opened 2 months ago so we'd need to check we are in sync. Not sure what the best option is for moving forward at this point.

[johnmccabe]

@alexellis / @ericstoekl I've squashed and signed the WIP commits - have not touched the rebase to make the outstanding changes more visible.

[johnmccabe]

Main guts of this change in its current state are as follows:

• CI build/deploy to GH pages via Travis
• Mkdocs docker based build
• The main changes were around an attempt to restructure the docs layout, primarily on the getting statrted flows - the K8s/Docker/PWD deploy guides were tweaker, and then getting started flow was broken into step sections, thats as far as I'd gotten to before I'd dropped offline - step 1 is ok, step 2 onwards were placeholders containing the original doc contents - effectively as a cache of original content that would be moved if necessary to other/new docs (at no point during the process did I want existing info to be removed from the repo).

To continue this would involve picking up on this getting started section, then some presentation updates around the guides sections etc to give a logical flow to them.

@alexellis the very long build time (17min+) appeared to be blips on the Travis side (occuring once) - builds times range from ~44sec to ~3minutes with the bulk of the time actually in the deploy step to GH Pages (the Travis logs suggest that the site build takes ~7sec consistently across all builds, its the docker run --rm -it -v $PWD:/docs squidfunk/mkdocs-material build --verbose --clean --strict step in the logs). You can have a look at the builds here - https://travis-ci.org/johnmccabe/faas/builds/

[johnmccabe]

Important

The .travis.yml has been updated to just build the docs - this is a temporary step, and the doc build/deploy step would be merged into the config on master before considering a merge.

[alexellis]

@ericstoekl you said you'd re-based this? Is there a PR?

[ericstoekl]

I'll have a PR up later today.

…

On Fri, Dec 29, 2017 at 1:45 AM, Alex Ellis ***@***.***> wrote: @ericstoekl <https://github.com/ericstoekl> you said you'd re-based this? Is there a PR? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#274 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABah_TPFk_of8Qn6y1G7E5Tth90J3ZL0ks5tFLTNgaJpZM4PzN8L> .

-- Erich Stoekl

[johnmccabe]

Closing as @ericstoekl is picking this up in #464

[alexellis]

ack @johnmccabe - feel free to input into #464 with Eric