Tag: github
Troubleshooting Deploying Documentation Using MkDocs
Recently, I was developing a package for my job. One of the requirements was to make
sure that it was properly documented. Being a big fan of Markdown, MkDocs
was a natural choice. Not only is it easy to pick up and customize, but Material for MkDocs
offers some fantastic functionality on top of it. With very little effort, you can add admonitions
(the nice colorful boxes with handy information), tables ,
site search , and many others.
After spending time and effort in writing the documentation per se, it was finally time to go live and deploy it. You can do this manually using GitHub Pages. However, in my case it was much handier to automate the documentation deployment after every push. GitHub Actions allow you to do this very easily. Unfortunately, this solution didn’t really work out of the box for me. In this post, I will share the problems I ran into and how I fixed them. Maybe this will be useful for someone else.
Using the .github directory in Enterprise Accounts
Among GitHub’s many cool features, you can create default “community health files” (e.g., CODE_OF_CONDUCT.md, FUNDING.yml, etc.) for all your repositories.
If you are working on repositories from your personal account, you can create a .github repository where you can place the corresponding files. Then, new repositories that you create will use these same files (unless you create community health files for each of them, in which case these will override the defaults). However, when working on an enterprise organization, there are a couple of considerations that you need to take into account to get this up and running.
Leveraging Cookiecutter to Publish Python Packages
I started working on my first Python package (which is far from ready, but I will definitely post about it when I have a version worth sharing). When trying to find resources of how to publish it to make it available for the community, I felt a bit overwhelmed. The setup for it to work properly involves a lot of individual files. These need to be in the right structure with the right content. As you can imagine, this is very prone to errors.
Creating a Shareable Bokeh Dashboard with Binder
Recently, I finished a personal project in which I analyzed the results of the “Who is your favorite Pokemon” survey. After that, I wanted to generate a more interactive visualization in which the user could choose a specific Pokemon and see its results. After pondering different options, I decided to do so in Bokeh because of a few reasons. First of all, you can generate your visualizations using Python only. Furthermore, it is very easy to incorporate Bokeh in Jupyter notebooks, which is great to generate a first version of the prototype. Lastly, a few colleagues of mine have used it for their projects at work and have been very happy with it.