Feature: docs deployment to GitHub pages via Actions #327

bandantonio · 2021-10-13T09:16:30Z

Overview

- Added static site generator to generate an HTML version of the documentation.
- Added GitHub Actions flow to deploy the documentation to GitHub Pages

Artifacts

Isomorphic Layout Composer (ILC) documentation site on GitHub Pages

… pages to work properly with the SSG

StyleT · 2021-10-13T09:48:50Z

docs/index.md

@@ -0,0 +1,112 @@
+![Isomorphic Layout Composer logo](./assets/brand/cover_small.png)


I don't think it's a good idea to copy/paste README here.

The idea is not to copy-paste it. We must have an index file for the documentation, that's why it appears here.
I would suggest shrinking the README file as much as we can (for example, describe only the major points) and for everything else - point to the documentation.
This PR shows the first step in this direction.

I don't really like the idea of shrinking the README file until we established website well. Now project gets most of it's traffic to the main page with README on it.

docs/global_api.md

docs/ilc_app_interface.md

StyleT · 2021-10-13T09:50:20Z

docs/installation_guide.md

@@ -10,7 +10,7 @@ In order to upgrade ILC to higher version you only need to replace running Docke
 in the following order: Registry first, ILC itself after. 
 So you should never have newer version of ILC running alongside outdated Registry. 

-To get more information about exact configuration of the Docker images see [docker-compose.yml](../docker-compose.yml).
+To get more information about exact configuration of the Docker images see [docker-compose.yml](https://github.com/namecheap/ilc/blob/master/docker-compose.yml).


Absolute links are not really good idea as it's hard to maintain them

Well, if you want to keep old files like global_api that only contain links to redirect users to a new destination, you will have to maintain those links anyway.

Furthermore, as the deployed version of the documentation consists of only static content (the files from the docs folder only), it is impossible to refer to the docker-compose.yml or any other file from the project folder using the relative paths - these files do not exist there.

I think it should be possible to correctly transform links with one of these plugins:
https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins#links--references

Also - this comment isn't really relevant for old files like global_api.

I Investigated a bit this topic and found a plugin that makes it possible to insert dynamic variables so that we can use something like that {{ repo_url }}/docker-compose.yml to refer to the source files in the repository.
repo_url is defined in the main configuration file mkdocs.yml so keeping all the links up-to-date will be an easy task.

StyleT · 2021-10-13T09:51:27Z

docs/stepbystep/index.md

Pls rename file back to README.md as it looks better in GitHub interface (README.md will be rendered here https://github.com/bandantonio/ilc/tree/feature/docs-deployment-to-github-pages-via-actions/docs/stepbystep)

It's not a problem, though, I'm wondering, does it make sense to worry about how things get rendered in the GitHub interface when there will be a fully-featured documentation view?

Yes, most of the traffic goes to GitHub

StyleT · 2021-10-13T09:52:28Z

.github/workflows/docs.yml

+      - gh-pages
+jobs:
+  build_docs:
+    name: Build documentation


Pls integrate with main CI flow. Should be after successful build & push to Docker repo.

BTW, there is one tricky aspect - do we really need build and push steps to complete successfully before generating and publishing documentation? (see line #148 in the ci.yml). I mean, there may be cases when you update documentation files only but build or push failed for some reason. In this case, the updated documentation won't be available until the CI steps are fixed.

Fun fact - currently, there is exactly the same situation I described in my previous comment. I cannot provide you with a link to generated documentation because the required steps failed and documentation generation was skipped.

.github/workflows/docs.yml

mkdocs.yml

… CI flow. Removed separate docs deployment workflow. Set dependencies for docs deployment

.github/workflows/ci.yml

StyleT · 2021-10-13T18:06:26Z

docs/index.md

@@ -0,0 +1,112 @@
+![Isomorphic Layout Composer logo](./assets/brand/cover_small.png)


I don't really like the idea of shrinking the README file until we established website well. Now project gets most of it's traffic to the main page with README on it.

StyleT · 2021-10-13T18:13:19Z

docs/installation_guide.md

@@ -10,7 +10,7 @@ In order to upgrade ILC to higher version you only need to replace running Docke
 in the following order: Registry first, ILC itself after. 
 So you should never have newer version of ILC running alongside outdated Registry. 

-To get more information about exact configuration of the Docker images see [docker-compose.yml](../docker-compose.yml).
+To get more information about exact configuration of the Docker images see [docker-compose.yml](https://github.com/namecheap/ilc/blob/master/docker-compose.yml).


I think it should be possible to correctly transform links with one of these plugins:
https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins#links--references

Also - this comment isn't really relevant for old files like global_api.

StyleT · 2021-10-13T18:13:51Z

docs/stepbystep/index.md

Yes, most of the traffic goes to GitHub

StyleT · 2021-10-13T18:15:30Z

@bandantonio let's discuss this in Skype Fri/Mon ;)

…ration workflow

… Made links to source files as external. Added corresponding icons to external links in the installation guide

… pages

…al section.

… github.com:bandantonio/ilc into feature/docs-deployment-to-github-pages-via-actions

…with build step only for master branch

bandantonio added 2 commits October 13, 2021 12:00

docs: added static site generator for the documentation. Revised docs…

bbf638b

… pages to work properly with the SSG

docs: added GitHub Actions flow to deploy documentation to GitHub Pages

603466c

bandantonio requested review from StyleT and nightnei October 13, 2021 09:16

StyleT suggested changes Oct 13, 2021

View reviewed changes

StyleT reviewed Oct 13, 2021

View reviewed changes

mkdocs.yml Outdated Show resolved Hide resolved

bandantonio added 2 commits October 13, 2021 16:19

docs: reverted deleted pages with links to docs from new locations

4980b07

docs: improved Actions flow: integrated docs deployment into the main…

e689efd

… CI flow. Removed separate docs deployment workflow. Set dependencies for docs deployment

StyleT suggested changes Oct 13, 2021

View reviewed changes

bandantonio and others added 8 commits October 14, 2021 13:40

docs: updated prerequisites for the documentation to be generated by ci

6c07958

docs: switched from docker to pip installation for documentation gene…

c2e5a02

…ration workflow

docs: added plugin to allow variables in page content

83ac1ff

docs: changed hardcoded links to variables in the installation guide.…

f437cd9

… Made links to source files as external. Added corresponding icons to external links in the installation guide

docs: added ignore rule for variable macro for several false-positive…

20097e0

… pages

docs: modified navigation structure. Added navigation tabs. Added leg…

c83d778

…al section.

chore: reduced code duplication

593f1f7

chore: reduced code duplication

064e32f

StyleT force-pushed the feature/docs-deployment-to-github-pages-via-actions branch from 593f1f7 to 064e32f Compare October 20, 2021 12:54

bandantonio added 2 commits October 20, 2021 16:12

Merge branch 'feature/docs-deployment-to-github-pages-via-actions' of…

7f76c16

… github.com:bandantonio/ilc into feature/docs-deployment-to-github-pages-via-actions

docs: modified ci step for documentation to use the local Dockerfile …

33e2010

…with build step only for master branch

StyleT approved these changes Oct 20, 2021

View reviewed changes

StyleT merged commit bffa590 into namecheap:master Oct 20, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feature: docs deployment to GitHub pages via Actions #327

Feature: docs deployment to GitHub pages via Actions #327

bandantonio commented Oct 13, 2021 •

edited

Loading

StyleT Oct 13, 2021

bandantonio Oct 13, 2021 •

edited

Loading

StyleT Oct 13, 2021

StyleT Oct 13, 2021

StyleT Oct 13, 2021

bandantonio Oct 13, 2021

bandantonio Oct 13, 2021

StyleT Oct 13, 2021

bandantonio Oct 15, 2021

StyleT Oct 13, 2021

bandantonio Oct 13, 2021

StyleT Oct 13, 2021

StyleT Oct 13, 2021

bandantonio Oct 13, 2021

bandantonio Oct 13, 2021

StyleT Oct 13, 2021

StyleT Oct 13, 2021

StyleT Oct 13, 2021

StyleT commented Oct 13, 2021

		@@ -0,0 +1,112 @@
		![Isomorphic Layout Composer logo](./assets/brand/cover_small.png)

Feature: docs deployment to GitHub pages via Actions #327

Feature: docs deployment to GitHub pages via Actions #327

Conversation

bandantonio commented Oct 13, 2021 • edited Loading

Overview

Artifacts

Choose a reason for hiding this comment

bandantonio Oct 13, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

StyleT commented Oct 13, 2021

bandantonio commented Oct 13, 2021 •

edited

Loading

bandantonio Oct 13, 2021 •

edited

Loading