In this project, the documentation is compiled locally and deployed to GitHub pages. The deployment url is: https://arquisoft.github.io/wiq_es3c/.
For the documentation, we are going to use AsciiDoc and PlantUML and follow the Arc42 template. If you want to be able to generate the doc locally you need to install Ruby, Java and some dependencies to translate the AsciiDoc code into html. If you are in Linux you can install Ruby and Java simply by executing:
apt-get install ruby default-jre
On Windows, you can use these instructions. Probably you will have Java already installed in your system, if not, you can download it here
Once Ruby is working you can install some gems with asciidoctor and asciidoctor-diagram.
gem install asciidoctor asciidoctor-diagram
Now it is turn to install some dependencies in the package.json file inside the docs directory:
cd docs
npm install
After installing these tools we can generate the documentation.
npm run build
The documentation will be generated under the docs/build directory.
If we want to deploy it to GitHub pages, so it is accessible via https://arquisoft.github.io/wiq_es3c/, we need to execute npm run deploy.
If you check the package.json in this directory you can see how deploying is as easy as executing gh-pages -d build, which can be directly executed using npm run deploy in the docs directory. The gh-pages package is in charge of pushing the documentation generated directory (basically some htmls) to a special github branch called gh-pages. Everything pushed to this branch is accessible on the repository page. Note that we only want to push there the documentation. Also is important that the documentation build is not pushed to the other branches of the project.