In one of my open-source projects - ReactiveNetwork I have a documentation in
README.md file and I have JavaDocs as well. This project is an Android library written in Java and built with Gradle. Moreover, I develop this project on two separate Git branches - one for RxJava1.x and another one for RxJava2.x. Similar convention is in the RxJava repository, so I followed it. After each release I publish documentation and JavaDocs on GitHub pages for both versions. It’s kind of boring and repeatable task, so I was wondering if there’s any way to automate it.
I have a Gradle task, which does that as follows:
and generates JavaDocs in
library/build/docs/javadoc/ directory. I keep generated JavaDocs on
gh-pages branch in
/javadoc/RxJava2.x/ directories. Now, I need to checkout to
RxJava2.x branch generate JavaDocs, switch to
gh-pages branch delete contents of
javadoc/RxJava2.x/ directory, copy contents from
javadoc/RxJava2.x/, commit changes, do the same for
RxJava1.x branch and push changes. As you noticed, It’s a lot of manual work. I’ve scripted it as follows in my
!/usr/bin/env bash # update javadocs for RxJava2.x git checkout RxJava2.x ./gradlew clean androidJavadocs git checkout gh-pages rm -rf javadoc/RxJava2.x/* cp -avr library/build/docs/javadoc/* ./javadoc/RxJava2.x git add -A git commit -m "updating JavaDoc for RxJava2.x" rm -rf library/build/docs echo "javadocs for RxJava2.x updated" # update javadocs for RxJava1.x git checkout RxJava1.x ./gradlew clean androidJavadocs git checkout gh-pages rm -rf javadoc/RxJava1.x/* cp -avr library/build/docs/javadoc/* ./javadoc/RxJava1.x git add -A git commit -m "updating javadocs for RxJava1.x" echo "javadocs for RxJava1.x updated" echo "javadocs for both RxJava1.x and RxJava2.x updated - now you can push your changes"
Generating user-friendly documentation
I keep my whole documentation for the user in
README.md file. In order to generate user-friendly website with documentation I used docsify. You can install it as follows via
npm i docsify-cli -g
gh-pages branch I’ve created
docs/RxJava2.x/ directories and copied there appropriate
README.md files from
RxJava2.x branches. Next I could go inside each directory and type:
docsify init .
Docsify generated nice website with documentation gathered dynamically from
README.md file. After that, I’ve done a few manual adjustments. Now, the only thing a need to do is to keep
README.md files updated. That’s why I made a script for copying
README.md files from
RxJava2.x branch into appropriate directories on
gh-pages branch and named it
#!/usr/bin/env bash git checkout gh-pages git show RxJava1.x:README.md >docs/RxJava1.x/README.md git show RxJava2.x:README.md >docs/RxJava2.x/README.md git add -A git commit -m "updating docs" echo "docs updated, now you can push your changes"
Now, I have boring process of generating Docs and JavaDocs for two separate Git branches automated and I can simply invoke my scripts:
./update_javadocs.sh ./update_docs.sh git push
and that’s it! You can see websites with documentation at:
and JavaDocs at:
I hope this article will give some ideas of automating your repeatable tasks.