docs(project): add initial setup for docs publishing

[bandantonio]

• added initial configuration for documentation static-site generator
• added index file based on the repo's README

[SyntaxRules]

Awesome start to standardizing the documentation in this project. Thank you! I'm not sure you are aware, but there is a site published on the gh-pages branch. How do you think this framework and that page should work together?

[bandantonio]

there is a site published on the gh-pages branch. How do you think this framework and that page should work together?

@SyntaxRules Yes, I've already inspected it a bit, and, as I understood, you're using a custom-written framework with mustache and bootstrap. That's OK for a small presentation-like website. If you are thinking about visual or functional updates (or even change framework completely), I don't mind. I will help with both activities. Documentation can also be integrated into this framework.

My question is - how html files are getting generated? I checked source files, but I didn't find any script related to building docs or deploying html to gh-pages. Or these files were pushed to the branch manually?

My base idea is to create CI/CD process for documentation to automatically build it on each commit/pull request (we can further configure CI/CD to update docs on specific commits). In this scenario, we can build docs using a static-site generator and then deploy html files under the /docs route (for example) as a part of the website framework files.

As a result, we will have website files hosted on the / route and documentation files hosted on the /docs route (physically, the docs sub-folder). The documentation section on the website will no longer be necessary.

[tivie]

For the website, I wrote a small blog-like custom framework, using moustache, bootstrap and showdown. I would prefer not to change the framework of the website for now since it's super optimized for SEO. (it can be improved, though. The mobile presentation, for instance, is not very neat). Also, there are a few third party tools that pull directly from the website to generate pub in facebook and other social platforms (which are important for our social network manager person, @Sophie-OS ).

The HTML is written and uploaded manually. All blog posts are markdown files which get loaded and parsed on the fly.

Ideally the same system should be used for documentation. Since mkdocs and "showdown site framework" use markdown to generate html, they can share the same source files.

And then you would have a docs directory in the base repo, with the static generated documentation html files. On the website, the md source files would be dynamically loaded and parsed.

Does it make sense to you? Can it work?

[bandantonio]

@tivie

it can be improved, though. The mobile presentation, for instance, is not very neat

Currently, I finished the same activity within my own project, so I can help with that.

The HTML is written and uploaded manually

I believe we should think on making the process of building the website along with the documentation automatically. This will dramatically reduce the time taken to review and deploy new website/documentation changes. Furthermore, we can set up docs preview (for example, for pull requests) to see how changes look like before deploying them to production.

they can share the same source files

They definitely can, but I think the website doesn't have to use documentation source files. If I understood you correctly, in this scenario, we would need to write custom build logic to convert and manage documentation files. This looks like reinvention of a wheel. Instead, we can incorporate mkdocs into the framework to build docs html files and then point the router to the index file inside the docs folder.

Hope this makes sense.

[tivie]

I believe we should think on making the process of building the website along with the documentation automatically. This will dramatically reduce the time taken to review and deploy new website/documentation changes. Furthermore, we can set up docs preview (for example, for pull requests) to see how changes look like before deploying them to production.

I think I didn't do a very good job explaining. Only the static assets are uploaded manually (the template written in HTML). Everything else is updated automatically, through http requests to the github api. For instance:

• website main page, the version in the download button is updated automatically, according to the latest version in the repository.
• releases page, it fetches the changelog and is updated automatically. As soon as you tag and create a new release in the github repo, the webpage updates.
• blog page, there's a directory in the ghpages branch called blog with a bunch of md. The page fetches those files and shows them. If you push a new md file to that directory, the page will show it.

This means you don't even need to build anything. When you release a new release, the website will fetch directly from the github API.

They definitely can, but I think the website doesn't have to use documentation source files. If I understood you correctly, in this scenario, we would need to write custom build logic to convert and manage documentation files.

Not really. That framework already parses markdown files using showdown. We might need to implement some type of navigation, which could be obtained from the mkdocs config file.

My base idea is to create CI/CD process for documentation to automatically build it on each commit/pull request (we can further configure CI/CD to update docs on specific commits). In this scenario, we can build docs using a static-site generator and then deploy html files under the /docs route (for example) as a part of the website framework files.

Btw, how would this be implemented? Would we need to add a python dev dependency? As far as I can tell, there's no native javascript port of mkdocs

[bandantonio]

@tivie Thanks for the explanation regarding the website. Regarding navigation, I believe it's not worth implementing something custom - it's better to use already existing solutions. Furthermore, mkdocs has everything we need out-of-the-box. It is a mature and actively developing solution that should fit our needs pretty well.

You can check the home page of the project, it uses a custom template for the home page, so it is possible to combine "showdown framework" to handle routing and use mkdocs to generate documentation exclusively.

Btw, how would this be implemented?

To better understand how documentation deployment works, you can check the actions YAML file of my own project. In terms of actions, to generate the documentation for showdown, we can use the Docker image. I would definitely try to combine the "showdown framework" with mkdocs. I've never done something like this before, it is an interesting approach.

[bandantonio]

@tivie @SyntaxRules I've successfully combined showdown website with mkdocs documentation. Please check the proof of concept in my fork: http://mister-gold.pro/showdown/

The config file for actions.

[tivie]

Good job! Thank you! Seems fine to me.

So, if I understand correctly, the workflow works like this:

• the documentation sources files (in markdown) are located in master:/doc/*
• when a new release is created, it triggers the workflow
• it grabs those sources files and generates the html documentation in ghpages:/doc/*

right?

Btw, in your repo there's a website directory that seems to be a copy of the ghpages. What is that?

[bandantonio]

• the documentation sources files (in markdown) are located in master:/doc/*

Yes. master:/docs/ to be accurate

• when a new release is created, it triggers the workflow

Yes, this is one of the possible cases. Here is a list of all events that trigger workflows.

• it grabs those sources files and generates the html documentation in ghpages:/doc/*

Not quite. The generator takes the files defined in docs configuration from the input folder and creates html documentation in the output directory. Deployment to GitHub Pages is a separate action.

Btw, in your repo there's a website directory that seems to be a copy of the ghpages. What is that?

You said that those website files are uploaded manually. So I decided to automate this step by including the website folder into the repo. During the Actions workflow, the website folder is copied into the same folder where html docs are generated (public). The public folder is then deployed to GitHub Pages.

Furthermore, as docs generation is automated via actions, if you try to deploy them, these files will override the existing files in the gh-pages branch. It means that website static files should be deployed along with the documentation files. So, the proposed workflow is a way on how to do it.

[tivie]

You said that those website files are uploaded manually. So I decided to automate this step by including the website folder into the repo. During the Actions workflow, the website folder is copied into the same folder where html docs are generated (public). The public folder is then deployed to GitHub Pages.

Furthermore, as docs generation is automated via actions, if you try to deploy them, these files will override the existing files in the gh-pages branch. It means that website static files should be deployed along with the documentation files. So, the proposed workflow is a way on how to do it.

I see... I'm not a big fan of mixing code and presentation. Having the website files in the master branch means changes to the website would create a commit in master branch, and that might clog the commit history, specially when testing stuff in the website. It will also make merges from develop branch to master more clunky.

@bandantonio @SyntaxRules @Sophie-OS What do you think about moving the website and documentation to another repository, namely showdownjs/showdownjs ? Works nice with gihub pages. https://pages.github.com/

Also, it might be possible to keep docs source files in the main repo and trigger an event that pushes to showdowjs/showdowjs

I think this way we can implement the awesome @bandantonio doc system and keep the main repo clean. What do you guys think?

[Sophie-OS]

@bandantonio @SyntaxRules @Sophie-OS What do you think about moving the website and documentation to another repository, namely showdownjs/showdownjs ? Works nice with gihub pages. https://pages.github.com/

I think that is the best idea. Currently I don't have permission to change or merge to master (and I don't want to), so it would be a pain to maintain the website. Having a new repo would make things easier.

[bandantonio]

I see... I'm not a big fan of mixing code and presentation.

I don't like it either. However, it is totally acceptable to have a couple of website assets and documentation source files next to the code.

Having the website files in the master branch means changes to the website would create a commit in master branch, and that might clog the commit history, specially when testing stuff in the website.

I don't see a problem here. You can checkout to a separate branch and do your cool things there. When you're done, you can squash all your commits and create a clean pull request. Basically, the same flow applies to the docs as well.

As an alternative, we can set up a separate branch for the website (for example, website, website-master, or gh-website) and keep all the stuff there. I think it would be possible to set up a workflow when the website files will be taken from that branch, whereas documentation source files will be taken from the master branch.

Having a separate repository to keep the website and html docs is also great, but this would require an extra effort to set up the proper workflow (an external event to trigger website and docs publishing).

[tivie]

Having a separate repository to keep the website and html docs is also great, but this would require an extra effort to set up the proper workflow (an external event to trigger website and docs publishing).

I think that is the cleaner solution. I will create a new repo, and give you the appropriate permissions

[tivie]

@bandantonio https://github.com/showdownjs/showdownjs.github.io I've deployed the website just for testing purposes and it's working correctly. You have admin access and green light to implement your solution.

I've also added @Sophie-OS as admin.

And thank you very much for your help!