feat(558): To use GitLocalize, use Jekyll instead of mkdocs. Add Japanese pages.

[kumada626]

Context

In Issue screwdriver-cd/screwdriver#558, we try to use GitLocalize instead of Locki. GitLocalize makes localized .md files in the repository. But MkDocs which is used in the screwdriver-cd guide does not support multi languages. Therefore, I experimented with using Jekyll instead of Mkdocs.

Objective

In this PR, I make the docs.screwdriver.cd page using Jekyll, and add Japanese localized pages.
To use Jekyll, I add front matter in exiting pages.
Jekyll does not have the built-in search feature, so that I use the jekyll-lunr-js-search Jekyll plugin.
We can see English pages and Japanese pages.

And we also can search. (The jekyll-lunr-js-search does not support Japanese, so we can search in English only. )

To use GitLocalize, we have to register the screwdriver-cd/guide repository in GitLocalize after this PR is merged.

References

Original issue: screwdriver-cd/screwdriver#558
Jekyll: http://jekyllrb.com/
jekyll-lunr-js-search: https://github.com/slashdotdash/jekyll-lunr-js-search
GitLocalize: https://gitlocalize.com/

[tkyi]

Hm. I like the idea of having trackable/reviewable translations. 👍

However, it looks like the jekyll-lunr-js-search is not as powerful/in-depth as the mkdocs search, if that screen shot you posted is up to date.

Old search:

[kumada626]

Actually, it looks that mkdocs search hits more results than jekyll-lunr-js-search. However, this because of the unit of results. Mkdocs search shows results in section units, on the other hand, jekyll-lunr-js-search shows results in page units. Therefore, all results shown in mkdocs search's results are included in jekyll-lunr-js-search's results. So that jekyll-lunr-js-search is less in-depth than mkdocs search, but as powerful as that.
Then, both searches return the same results unless we need to show results in section units.
Do we have to show results in section units?

[petey]

Seems like a good plan. Can you update the PR so that it includes the most recent guide changes?

[tkyi]

Sorry about all the guide changes! 🙇‍♀️

[kumada626]

I included the most recent guide changes.

[tkyi]

Can you also update the README with instructions for how to run the guide locally?

[petey]

This PR is re-adding files that were deleted, and shouldn't be in use by the current theme. Can you make sure that main_bkgrd_home.png and Screwdriver_Logo_White.svg are not actually used, and update the screenshots?

[kumada626]

I updated the README and screenshots, and deleted files that are not actually used in the current theme.

[petey]

I do think that the lack of any context in the search results, as @tkyi mentioned, is going to be a big problem. Is that something that can be tweaked?

I'm also having a lot of issues getting jekyll to work per the directions in the readme. I eventually got it to work by running bundle install followed by bundle exec jekyll --version, but it doesn't seem like that is the intended way to run this.

You may also want to document how you get to alternate language versions of the docs.

[kumada626]

jekyll-lunr-js-search cannot be tweaked to display the context in the search results. Therefore, I use lunr.js instead of jekyll-lunr-js-search. Now, the display of the search results is below.

In the readme, I fixed the way to get jekyll to work. When use the jekyll, we use the bundler.

And add the document how you get to alternate language versions of the docs in the Browse your local guide section of readme.

[petey]

[tkyi]

[minzcmu]

Ah, this probably won't work without source ./ci/git-ssh.sh.
Inside the git-ssh script, it will use the GIT_KEY to setup ssh for you so that you can push

[kumada626]

I added source ./ci/git-ssh.sh command in the deploy.sh.