Improve documentation

[Diapolo10]

The current state of the project's documentation isn't great - everything is in the source code and README and lacks details.

[RaamAnalyst]

I am interested in documentation for this project.

[Diapolo10]

Go right on ahead! Unfortunately I just made major changes to the build system on the nightly branch and there's some issues I need to address, so that's taking my time right now.

[RaamAnalyst]

That's fine. I will start working on this documentation.

[Diapolo10]

Feel free to ask about anything you don't understand, I'm probably the only person who knows the ins and outs of this codebase.

[RaamAnalyst]

Sure. I will reach you for any clarifications.

[Diapolo10]

Hi @RaamAnalyst, sorry to mention you out of nowhere but if possible I'd like you to move the documentation you wrote to the docs folder. As it stands, the README-file is just too complex and long for what is supposed to be just a quick briefing of what the library is about. Also, please push changes to nightly instead of directly to main, as that will trigger the automatic release system of the CI/CD pipeline and that will fail if the version number isn't updated - among other things, as main is used for the latest stable build.

Furthermore, my linter went nuts when I tried to merge the changes made to the main branch to the nightly branch, some things you documented were basically completely unnecessary (like repr-support, as everything in Python supports them; the reason they appeared in the original README was just to show how they'd roughly look), and the way you worded some things just sounded weird. Example:

Different Formats of IP Address IPv6

IP Address of IPv6 exists in different formats.

Example:

foo = IPv6('[::1337:1337:1337:1337]:25565')
bar = IPv6('::1337:1337:1337:1337', 25565)
baz = IPv6('::1337:1337:1337:1337', port_num=25565)
print(f"Addresses are {'equal' if foo == bar == baz else 'not equal'}")
print(baz)

Output:

Addresses are equal
[::1337:1337:1337:1337]:25565

For instance, here's how I tried to rewrite this for the nightly branch while fixing the merge conflicts (even if I ultimately reverted the merge as being too much work). You may note the changes in raw Markdown if you can see it somehow:

Different ways to initialise IPv6 objects

iplib3.IPv6 can be initialised in several ways, here are some examples.

foo = IPv6('[::1337:1337:1337:1337]:25565')
bar = IPv6('::1337:1337:1337:1337', 25565)
baz = IPv6('::1337:1337:1337:1337', port_num=25565)
print(f"Addresses are {'equal' if foo == bar == baz else 'not equal'}")
print(baz)

Addresses are equal
[::1337:1337:1337:1337]:25565

Here, calling the three different 'formats' sounds really weird to me. The heading makes no grammatical sense, and the linters mostly complain about the lack of empty lines and suddenly going from ### to ###### in headings, as well as the repeated use of "Example" and "Output" as headers.

I know, this probably sounds nitpicking and annoying to you. That's perfectly understandable, and for my part I never really specified these things beforehand while I obviously should have set some guidelines so it's not like this is your fault. But if you're up for it, I'd love for you to move all this (and more) to the docs folder as proper documentation. README isn't documentation, though it can have a link to it.

[RaamAnalyst]

Yes. Sure. Thanks for your valuable feedback.

[Diapolo10]

I truly appreciate it! Got the build system sorted out now, currently focusing on breaking down some parts of the codebase that are too "complex" (according to Flake8, anyway). Test coverage is currently 100% on the nightly branch, so my next focus is on getting the subnets to be used by the address classes. And breaking down the unit tests into more chunks.

[RaamAnalyst]

Great work. Congrats.

[Diapolo10]

Been a bit busy with work lately, but I added the project to https://readthedocs.org to make documenting easier and more standardised: https://iplib3.readthedocs.io/en/latest/

I'll probably make/add a GitHub Actions workflow that auto-updates the documentation on merges to the main branch at some point (likely soon-ish since it shouldn't be much work), but for now, I'm studying the tutorials for the service: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html

[RaamAnalyst]

Your choice is great. Read the Docs is one of the best options for easy and standard documentation.