Latest Documentation?

[karimbahgat]

I haven't been following the latest developments on this project, but I see there's been a lot of new activity + bugfixes + new features. I hope to be using the latest version going forward however, so am in need of the latest documentation describing the latest API, especially now that the original effbot docs are down. I was trying to browse the code repo but couldn't seem to find anything, and reading the actual code is not as easy as it seems to be hidden in the various .cxx files which I'm not fully sure how to navigate.

• Where are the current documentation files, if any? If there's currently none, I would like to help out, but would need some pointers how and where to start. I think this should be fairly doable, since the original API and docs was fairly short/straightforward.
• And/or could someone list the main new developments achieved so far compared to the original aggdraw?

Otherwise, loving all the progress and work to keep aggdraw alive, and especially excited about potentially exposing new agg features like gradients or fillpatterns etc.

[djhoese]

Check the right side of the main repository page: https://github.com/pytroll/aggdraw
Has a link for https://aggdraw.readthedocs.io/en/latest/ and these files come from the doc directory in the main repository and are built by readthedocs. The CHANGELOG describes what's changed: https://github.com/pytroll/aggdraw/blob/master/CHANGELOG.md

That is the closest to effbot's old docs with some improvements. I don't think there is anything necessarily missing compared to effbots stuff but yeah it needs usage examples.

There aren't many new features right now except the master branch has a new version of libagg BUT it doesn't produce the exact same output which is why it hasn't been released. See the existing issues in this repository for examples of these issues and other plans for this project.

[djhoese]

The docs are also the first result on google:
https://lmgtfy.app/?q=aggdraw

😜

[karimbahgat]

Oops, i guess i was a little too quick there :P I saw the doc folder but couldn't see any of the html output, only the scripts to dynamically build the docs which I assume are excluded in gitignore.

I guess that partly answers my question, if I wanted to help with any docs, I would simply go in aggdraw.cxx and edit the related docstrings, as these are the basis for the doc generation.

Some questions remain however:

• If one wanted to suggest edits to the introductory parts of the docs (before the class docstrings), where is that defined?
• I see the Dib() class is missing from readthedocs, is there a reason for that?
• Most importantly, while the Draw class docstring is included on readthedocs, the docstrings for its various draw methods seem to be missing? This is probably the more important part of the docs in terms of the different things that can be drawn and the required parameters.

Let me know if there's any particular ways I can help with these.

[djhoese]

The main started document for the documentation is https://github.com/pytroll/aggdraw/blob/master/doc/source/index.rst
The doc folder is a standard sphinx project. If you haven't used sphinx before then it may be easiest to google for a sphinx tutorial just to get an understand of the structure and basics of generating the documentation. In general it is considered best practice to not store the generated HTML.

The Dib class is only included on Windows systems:

aggdraw/aggdraw.cxx

Lines 2564 to 2575 in 4c7594d

	static PyMethodDef aggdraw_functions[] = {
	{"Pen", (PyCFunction) pen_new, METH_VARARGS|METH_KEYWORDS, pen_doc},
	{"Brush", (PyCFunction) brush_new, METH_VARARGS|METH_KEYWORDS, brush_doc},
	{"Font", (PyCFunction) font_new, METH_VARARGS|METH_KEYWORDS, font_doc},
	{"Symbol", (PyCFunction) symbol_new, METH_VARARGS, symbol_doc},
	{"Path", (PyCFunction) path_new, METH_VARARGS, path_doc},
	{"Draw", (PyCFunction) draw_new, METH_VARARGS, draw_doc},
	#if defined(WIN32)
	{"Dib", (PyCFunction) draw_dib, METH_VARARGS, dib_doc},
	#endif
	{NULL, NULL}
	};

Readthedocs is generating the docs on an Ubuntu system (iirc) so aggdraw never presents this function/class. We'd have to update the Dib code to be importable but not runnable on non-Windows (maybe raise a RuntimeError or OSError if used on non-Windows).

My guess on the Draw methods missing is due to the poor design of aggdraw.cxx. The classes aren't actually classes, they are functions that produce instantiated objects. So when the sphinx generation runs and looks for the docstrings it can't find these "methods on a class" because there isn't actually any class. There are various issues on this repository about rewriting aggdraw to do this the right way (probably use Cython). I could see a small workaround being to append the method docs to the main Draw docstring, but I'm not sure how ugly this would get code wise and is asking for mistakes in the future.

Any helps on the docs is appreciated. Most important to this project as a whole is to figure out what happened in newer versions of agg (the C/C++ library) to make the output not the same. Once we can make a release of aggdraw that produces the same results (or near the same) then we can rip it apart and rewrite it with modern best practices/standards.

[karimbahgat]

Thanks, this is all good info. Until the cxx can be reworked sometime in the future, I think it would be good to find a makeshift way to get the full complete documentation, maybe by stringing together the various docstring constants as you suggested. Some food for thought, I'll see if I can throw together a PR at some point.

[djhoese]

Oh yeah if at the C++ level the docstrings could just be appended strings that might be the least amount of duplicated code/documentation.

[setanarut]

the original effbot docs are down

full doc;

https://web.archive.org/web/20200719080546/https://effbot.org/zone/pythondoc-aggdraw.htm