Ever made a library, added documentation and then thought “Ugh I need to make this into a website so my users can see whats there. Why is it so much work?”. Here is the solution to your problems. (No fixes for demotivation sorry)
Note: This only works for Python code. It will work perfectly on Linux/MacOS/WSL with no issues. Windows.. you might need to change the commands to suit your shell.
What you will have by the end of this short tutorial
- An interactive website with all your modules, sub modules, classes documented nicely. It will even show code!
- No need to touch HTML/CSS/JS anything. Just code. And write comments
- A site hosted on Github pages that auto updates so you can share it with your users. (Or host it elsewhere)
- Example : Site1 , Site2 (These are from two of my projects)
- You are using Github. Since we are using Github pages, you need to store your repository on Github. (Of course you could do it some other way but that is too much work and we are lazy.)
If you are not sure how to go about doing that, I suggest you have a look at this article
- Your code-base is in Python.
- You are using Linux/MacOS/WSL
- You have pandoc installed (pip install pandoc)
- Since you made a library, the folder structure should be similar to this
Follow these steps
- Now in each of the files, add documentation to your functions/classes. Just go to the first line after the function/class definition and add a multiline comment with whatever you wish to say.
- Go to the parent directory and run
This should generate the required files.
- Now for the hacky part of it. (It works trust me)
- Now go to your github repository
- Click settings and open the “Pages” pane (to the left)
- Click source -> master for branch and select /docs in the folder option. (These were auto generated)
- Click change theme and choose a theme you like. (This is important!! Do not skip it)
- Then hit publish! And you are done :)
- You will get a link to your own website.
- Sit and admire how beautiful it looks and cry you didn’t know how to do this before
- You can always customize your page using Jekyll.
- If you want documentation for an entire module, add a comment right after the imports/ at the start of the file
- You can even change the domain to be on your custom one (if you own any)
- Make a shell script!! We are lazy. Why bother doing the same things a billion times. — Create a file called pusher.sh (Or anything you want)
- In the file just pop the above commands. If you want add code formatting with black/isort as well. I have also added a little shell command which lets me push to github easily
And we are done :)
Enjoy and happy building your sites!!