Manim: Add nonzero documentation

[faielgila]

Includes deciding on a library and implementing a way to deploy documentation somewhere public.

[yoshiask]

On the Manim Discord, we have settled on pdoc

[safinsingh]

Just so you guys know, you can run pdoc --html manimlib to generate the HTML docs when the docstrings are finished.

[yoshiask]

Is it worth generating and publishing the documentation we have so far? All of Scene is done, and that's not a trivial amount of information.

[eulertour]

I'd say it is so that we can be sure we actually can.

[Aathish04]

I can confirm that pdoc does work.

However (this is specific to my system) I had to remove all references to SceneFromVideo (OpenCV wasn't installing on my system.)

In addition to that, the formatting is a bit off, but that is easily fixed.

[leotrs]

@yoshiask can you please briefly summarize the reasons why we settled on pdoc? I'm not opposed, I'm just curious.

Also, I think that the style of docstrings is more important than the actual software used to parse them. Are we using numpy docstrings? If so, it doesn't really matter whether we use pdoc or sphinx for now, as we can change it later (without changing the docstrings).

[PgBiel]

I'm in favor of using sphinx, it's a very customizable tool and, when used correctly, produces very nice documentation.

Also, numpy docstrings are more readable imo

[Aathish04]

As of now, we know both Sphinx and PDoc work.

I think it would be better to focus on getting the documentation done in the form of good, formatted docstrings perferably in NumPy format, after which we can select the parser with which the more "beautiful" docs can be made.

Also, the Docstrings I've written follow no specific format and jump between Numpy and standard documentation formats because halfway through I got confused between them :/ ...

[leotrs]

An argument against pdoc is that it only generates documentation from docstrings. If we want to write a tutorial and host it in the same place as the auto-generated documentation from docstrings, that would be very hard to do, it seems. Sphinx allows us to do both at the same time.

This is apparently not true.

[yoshiask]

An argument against pdoc is that it only generates documentation from docstrings.

@eulertour looked into it and he concluded that it was in fact possible to add docs independent of actual Python code.

Also, I'm partial to pdoc because it supports LaTeX equations inline with docstrings, which will make some classes (like space_ops.py) easier to document.

[leotrs]

An argument against pdoc is that it only generates documentation from docstrings.

@eulertour looked into it and he concluded that it was in fact possible to add docs independent of actual Python code.

Ah excellent!

Also, I'm partial to pdoc because it supports LaTeX equations inline with docstrings, which will make some classes (like space_ops.py) easier to document.

Sphinx can also do this.

I think another thing to consider is, where do we want to push the documentation? I don't think ReadTheDocs supports pdoc.

I think we are at a point where we really need someone to be the "lead of documentation".

[PgBiel]

Sphinx can also do this.

Yes; I was about to say this. Worth mentioning that Sphinx has a handful of extensions. It's worth it to check them out.

[Aathish04]

I think another thing to consider is, where do we want to push the documentation? I don't think ReadTheDocs supports pdoc.

The current Documentation generator _is_ sphinx, and the (extremely incomplete) Docs are currently hosted at ReadTheDocs.

pdoc may not be supported by ReadTheDocs, but it has better support for deploying directly to GitHub pages, which IMO is kind of neat, since we can keep everything local to this repo, nice and self-contained.

Sphinx can do everything pdoc can do, and definitely more, and pdoc is a lot simpler to use.

What do we want more? Simplicity for getting the docs out (pdoc), or having the ability to expand if needed from the get-go (Sphinx)?

[PgBiel]

but it has better support for deploying directly to GitHub pages

Source?

[Aathish04]

but it has better support for deploying directly to GitHub pages

Source?

Crap. You're right, it doesn't have support for anything like that...

https://github.com/pdoc3/pdoc/blob/master/.github/deploy-gh-pages.sh

I took a glance at that file and thought it was a quickstart for deploying our own docs to GH Pages.

If PDoc doesn't have that advantage..

Yeah, I'm leaning more towards Sphinx now...

[leotrs]

What do we want more? Simplicity for getting the docs out (pdoc), or having the ability to expand if needed from the get-go (Sphinx)?

This is exactly the point. Well said. I personally lean toward flexibility (sphinx).

But once again, we need to designate someone to make decisions about documentation.

[Aathish04]

If it were me, I would use Sphinx. It seems to be more easy to use than PDoc is flexible.

I _am_ willing to look over the Documentation stuff, if that's fine by you guys.

[leotrs]

I think @yoshiask and @eulertour may also want to claim the "docs lead" spot.

There is, of course, only one civilized way to decide who claims it. Mortal Kombat.

[eulertour]

These are the things that annoyed me with Sphinx / made me want to try pdoc:

1. Linking to other documentation is more cumbersome in Sphinx
   The syntax has the form :class:`~mobject.geometry.Square` as opposed to mobject.geometry.Square in pdoc. [[sphix doc](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects)][[pdoc doc](https://pdoc3.github.io/pdoc/doc/pdoc/#linking-to-other-identifiers)]. But looking at this more I see that pdoc doesn't offer the ability to have only the last part of the path to appear in the generated link by prepending ~.

1. Sphinx always looks ugly. It probably has something to do with how complicated it is to template with it [[sphinx templating](https://www.sphinx-doc.org/en/master/templating.html)][[pdoc templating](https://pdoc3.github.io/pdoc/doc/pdoc/#custom-templates)].

But that's really it. Thinking about it some more if we're going to have to deal with reST and HTML templating in either case it may just be worth it to get the benefit of Sphinx's larger community support.

[leotrs]

1. Agreed, sphinx can be cumbersome, no contest there.
2. I agree that default sphinx is super ugly. However I have successfully used the ReadTheDocs themes with sphinx and once it is setup, it is not half bad.

I think we can deal with 2. And I'm not sure that 1. is sufficient reason to not use sphinx.

[eulertour]

SGTM, we can go with Sphinx then.

[PgBiel]

These are the things that annoyed me with Sphinx / made me want to try pdoc:

1. Linking to other documentation is more cumbersome in Sphinx
   The syntax has the form `` :class:`~mobject.geometry.Square` `` as opposed to `` `mobject.geometry.Square` `` in pdoc. [[sphix doc](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects)][[pdoc doc](https://pdoc3.github.io/pdoc/doc/pdoc/#linking-to-other-identifiers)]. But looking at this more I see that pdoc doesn't offer the ability to have only the last part of the path to appear in the generated link by prepending ~.

Well yeah, it's because of the specific syntax for it; everything has a meaning. However I do agree this can be annoying at times... I think most editors should support it and automatically highlight it on doc previews but not sure

2. Sphinx always looks ugly. It probably has something to do with how complicated it is to template with it [[sphinx templating](https://www.sphinx-doc.org/en/master/templating.html)][[pdoc templating](https://pdoc3.github.io/pdoc/doc/pdoc/#custom-templates)].

Oh no, we won't build this entirely by ourselves; there are many pre-made models and themes out there!

[leotrs]

@yoshiask thoughts? Are you ok with using sphinx?

[yoshiask]

@leotrs I'm fine with using Sphinx, but I have not been able to get it to work on my machine.

[leotrs]

@yoshiask I'd be glad to help debug that particular problem (once there are some docs to speak of).

Well, it seems like we have reached consensus. We are leaning toward sphinx. I suggest we keep this open a bit longer in case any of the other devs want to chime in. Or until we designate a lead of documentation, who can then declare this done. Whatever happens first.

[faielgila]

So, to be clear: we're settled on Sphinx?

[leotrs]

I count five out of 7 participants on this issue are in favor of Sphinx (the other two don't seem to be against?). That sounds like enough votes to me.

[leotrs]

But also, @kilacoda is sort of in charge of the docs branch, so I'd like to hear what they think.

[kilacoda]

I haven't really used pdoc, ever, so I guess this may be biased but... yeah, Sphinx would be good. Especially considering it'll easily integrate with ReadTheDocs. If we go with numpy/Google type docs we can use the napoleon sphinx plugin so that won't be a problem at all.

[kilacoda]

Also, going on a bit of a tangent here, but are we aiming for a better reference manual type of documentation or docstrings-that-open-up-on-hover kind of docs?

[leotrs]

@faielgila I think it's safe to say we're doing sphinx.

@kilacoda I would aim to have numpy-style documentation, where each of the main classes has a 2-3 page docstring, complete with examples and cross-references. Of course we can leave that for the future. More documentation can't really hurt at this point.

[leotrs]

I think this issue has ran its course. We have landed on sphinx and numpy style docstrings. There are other efforts happening RE documentation. So I'm closing this.