Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Switch to mkdocs #2

Open
andre2007 opened this issue Jul 4, 2018 · 4 comments
Open

Switch to mkdocs #2

andre2007 opened this issue Jul 4, 2018 · 4 comments

Comments

@andre2007
Copy link
Contributor

I did some closer look on mkdocs as tool for generating a nice documentation site for intellij-dlanguage.

An example page created with mkdocs you can see here:
http://opensciencegrid.org/security/

The concept is rather easy. On master branch you write the markdown files. There is a second branch gh_pages which contains the generated documentation based on the markdown files.
A travis CI job automatically creates and upload the files to the gh_pages branch on push to master branch.

Setting up travis ci is described here
https://djw8605.github.io/2017/02/08/deploying-docs-on-github-with-travisci/

@SingingBush
Copy link
Member

I'm open to using mkdocs. As this is a organization page though there's no gh_pages branch, we just push to master.

@andre2007
Copy link
Contributor Author

I am not sure what you mean with organization page. I think 2 branches are necessary:

  • master: contains the source code (the markdown files). Merging pull requests into master triggers the Travis CI job to compile(translate) the markdown files into html files
  • gh_pages: contains the generated html files. https://intellij-dlanguage.github.io/ will point to the gh_pages branch

Maybe it is possible to have the markdown and the generated html files in 1 branch (master) but then you have to invest more time into the travis CI logic. Pushing the generated html files should not trigger the mkdocs process again -> endless loop

@andre2007
Copy link
Contributor Author

I started to create a mkdocs prototype. Unfortunately the actual version of mkdocs has a bug while deploying to User/Organization pages. mkdocs/mkdocs#1525
This bug will be solved with next version of mkdocs. I assume version 0.17.6.
When the version is available I will continue working on this topic.

@waylan
Copy link

waylan commented Jul 11, 2018

This bug will be solved with next version of mkdocs. I assume version 0.17.6.

Not version 0.17.6, but version 1.0. This was not a bug with a simple bugfix. Previously, MkDocs did not support User/Organization pages. To add support, we needed to make a backward incompatible change to how relative paths in the config file are resolved (see mkdocs/mkdocs#1376 for details). Therefore, this change will be part of a major release.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants