Integration with Read the Docs

[mattgwwalker]

Hi Zuzu-Typ,

I merged in pull request #39 and started with the process of registering the project with Read the Docs, however it appears I lack the permissions required.

Would you prefer to go through the process yourself? Otherwise, if I understand correctly, you'd need to grant me Admin-level access to the project, as only Admins have the ability to manage webhooks, which Read the Docs depends on.

If you'd prefer not to give me Admin-level access, you can go through the process yourself. You'll need to set up an account with Read the Docs and follow their instructions.

Cheers,

Matthew

[mattgwwalker]

I have done a bit more reading about permission levels.

It seems that because the project is owned by an individual (you), there are only two levels of permission: owner and collaborator. Note that owner is in the singular, as you can only have one of them per project.

I understand that the solution to this is to use GitHub's Organization feature. I have created an organization "TeamPyOgg" and I have invited you as a (joint) owner of the Organization. The organization would effectively become the owner of the PyOgg project. This will allow us both to have Admin-level access to the project.

Cheers,

Matthew

[mattgwwalker]

I forgot to add that once the organization is set up the repository needs to be transferred to the organization.

[mattgwwalker]

Awesome. Thanks @Zuzu-Typ. I've just checked and the repository has been transferred. The original address (https://github.com/Zuzu-Typ/PyOgg) now takes me to the TeamPyOgg version (https://github.com/TeamPyOgg/PyOgg). I also have access to webhooks. I'll look into setting up the documentation today.

Do you still have full admin access to the repository?

Matthew

[mattgwwalker]

The documentation is now partially building. You can see it at https://pyogg.readthedocs.io/en/latest/

However there is an issue in the the API documentation isn't appearing correctly. This is because Read the Docs (reasonably) do not want to install the pre-compiled binaries. As a consequence, when PyOgg is imported it is not using the normal classes but rather those defined in the case that it cannot find the required libraries. And thus the automated documentation is not documenting the normal classes.

I will look into this further.

[mattgwwalker]

The documentation appears to be building correctly now.

To achieve this I extracted out the classes from __init__.py and placed them in their own files. The code that decides if the class will be the "normal" or "error" class is identical.

The documentation then specifically references the classes defined in their independent files rather than the classes that are defined in __init__.py.

This also had the advantage of resolving issue #38.

I've also updated the README file (that appears on GitHub). It now has links to the Read the Docs site and a badge telling us the state of the latest documentation build.

Next on the list is to activate the hooks that automatically re-build the documentation when we update it.

[mattgwwalker]

Done.

The webhooks now work: whenever we push commits, the documentation will now be rebuilt automatically.

As a test, I moved us to the Read the Docs theme, which keeps us in line with almost all the other packages on that site.

I'll close this issue.

Matthew