Outreachy Report V
This is the fifth post on my internship on the Outreachy Program with Project Jupyter. The previous posts are available and should be read in order if you want to understand the big picture:
Increasing documentation
Native Authenticator was pretty advanced, but we still needed more information available on the documentation. And this got me thinking: what is relevant to make a good documentation? I know some good examples of a good documentation and an big amount of awful ones. I read an article in portuguese on how to do a good documentation but it still didn’t click to me.
This is something particularly weird for me: I love writing technical blog posts but I don’t think I am good writing documentation.
For doing a good documentation I did three things:
1. Added “big pictures” sections
I just let the first page of the documentation have the description of what Native Auth has of features (both optional and default). After that, I created a session called Default Workflow that gives an idea how the authenticator works in the default manner. I used the fluxograms I created for my blog posts to make it easier to have an idea how it works.
2. Added documentation on basic things
I documented then somethings that are, in a way, trivial, but people would need to go to the code to see it. This included how to create new users, restrictions that the authenticator imposes and links to other features available (authorization area and change password endpoint).
3. Added optional features
I created a single document with all optional features we have, since it is not a great amount of them and the description for each are kind of short. I added more fluxograms everywhere I thought was relevant, most of them derived from the ones I used in previous blog posts.
…
I thought that the result was good enough, but please feel free to either contribute or open an issue if you see any possibility of improvement! 🤓
People are using it
Something weird started to happen this month… people were using the project.
A person reported problems with installation and another opened a pull request that tried to fix that bug.
Then I had another pull request to review and I asked the person to break it into two new pull requests, to make things easier to manage.
This was pretty exciting! I haven’t even launched the library yet and there are people using something I did! Awesome!
Launched Native Authenticator on Pypi!
Documentation in order, we could launch the library on Pypi!
I followed this instructions to deploy it. However, I didn’t understand (at that time) why would we should put the packages on TestPypi instead of the Pypi.
I launched the version 0.0.1 and the problems started: it couldn’t find the templates. I tried the distributions locally and everything worked, I launched it on Pypi… nothing. I thought “that’s ok! I delete the packaged from the Pypi and add it again with the same version number”. Guess what? You can’t. That’s why you have TestPypi. Dãã. Seriously: don’t launch on Pypi unless you are absolutely sure it is stable. And use TestPypi to do this 😅.
Finally, the setup for adding files was this: I added the line include_package_data=True on the setup.py and a Manifesto.in to list the filed I want to be with the package. By the way, the last stable version is actually number 0.0.4.
This is the documentation on adding packages on a library, because theoretically the way I did is not the only way.
Writing about the project
I also spent a couple days working to write an official blog post on the Jupyter Blog to share the new authenticator to the world.
The article is still under revision, but it will be out soon (maybe this week). You simply can not imagine how happy I was when I saw this on my Medium account:
This is something amazing for me and truly an honor.
Starting to add the project to The Littlest JupyterHub
I started to get in touch with The littlest JupyterHub (TLJH) which is distribution of JupyterHub for 1 to 50 users in a single server.
We will add Native Authenticator as the default authenticator for TLJH, so I needed to understand better how this distribution works.
I started by adding the Native Auth as an option for people that uses TLJH, which included default instalation and some docs. However, one thing that is missing to change authenticators, as pointed out by Yuvi’s issue, is a way to import users from the default authenticator to Native Authenticator. We don’t want people to loose access when changing the authenticator, right?
I’m still working on this, so you’ll know more about it in the next report!
Going to Jupyter team meet in Washington DC
An amazing thing that happened to me this month was knowing I’ll be able to attend the Jupyter in-person team meeting that will happen in Washington DC! It will be a full week of working with people that admire so much! I am counting the days for the next 3 weeks 🙃
My internship will end in mid-March, so it will most certainly end in huge style! Not only that, but I get the chance to see Carol, 3 years after she helped me have a wonderful time at Pycon.
All communication and definitions of the team happens on this repository and you will see all the information about the in-person meeting in this issue.
So, if you like my texts, you probably get one about this week in April or so! I intend to do something similar to what I did when I went to Pycon 2016 with the conference financial aid.
❤ Cheers! Letícia