write documentation

[johnyf]

There is currently no user documentation in tutorial form, besides the docstrings, as #129 underlines.

[leycec]

👍 👊

I suspect most end users currently leverage the online pydotplus and pydot-ng documentation, which is clearly suboptimal.

[johnyf]

The pydotplus docs appear to be the docstrings, no user documentation added, no tutorial. pydot-ng docs appear to be empty.

[johnyf]

As part of this issue, incorporate information from the branch: https://github.com/erocarrera/pydot/tree/wiki, and then delete the branch wiki.

[ian-bertolacci]

Pinging issue.

[danpalmer]

Ping.

[peternowee]

I just opened PR #253, adding some basic usage examples to the README. I hope it is accessible enough for newcomers. Suggestions for improvement would be very welcome, preferably this week then. I am hoping to merge it next weekend.

(Note that this will not close this issue #130 yet, but only #141.)

[brando90]

does this mean that pydot doesn't have docs like these: https://pygraphviz.github.io/documentation/latest/tutorial.html can someone explain to me how people actually know how to use pydot then? is there an api page or something? or just based on the initial tutorial on the read me?

[brando90]

👍 👊

I suspect most end users currently leverage the online pydotplus and pydot-ng documentation, which is clearly suboptimal.

I am genuinely curious, why is pydot so widespeard (e.g. ~15k users pydot vs 4.1k users for pygraphviz) if it doesn't have docs? Doesn't it make it hard to use?

[julianfortune]

can someone explain to me how people actually know how to use pydot then? is there an api page or something? or just based on the initial tutorial on the read me?

I am genuinely curious, why is pydot so widespeard (e.g. ~15k users pydot vs 4.1k users for pygraphviz) if it doesn't have docs? Doesn't it make it hard to use?

I was able to figure out how to use PyDot for my use case quite easily (~20 minutes) using the README.md, GraphViz documentation, and a dot example of my use case. Does this help? What specifically are folks looking for in PyDot documentation?

[balqui]

can someone explain to me how people actually know how to use pydot then? is there an api page or something? or just based on the initial tutorial on the read me?

I am genuinely curious, why is pydot so widespeard (e.g. ~15k users pydot vs 4.1k users for pygraphviz) if it doesn't have docs? Doesn't it make it hard to use?

I was able to figure out how to use PyDot for my use case quite easily (~20 minutes) using the README.md, GraphViz documentation, and a dot example of my use case. Does this help? What specifically are folks looking for in PyDot documentation?

Well, I don't know about folks, but I for one would be looking for clarification on unsupported attributes and whether workarounds exist. Or for explanations of the following raising an error (possibly for the same reason):

Python 3.6.9 (default, Jan 26 2021, 15:33:00) 
[GCC 8.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import pydot
>>> g = pydot.Dot("a")
>>> s = g.create_dot()
>>> ggg = pydot.graph_from_dot_data(g.create_dot())

Our use case requires accessing the positions set up by the dot layout engine, and pygraphviz allows for it and documents how to do it... provided that we manage to install it; as, right now, it works only on two thirds of the involved systems. (Brando90: one possible explanation is that after installing pydot, it works, while after installing pygraphviz it may work, or it may not.)