Vezzra wrote:Why? AFAIK that's actually "common standard", reference manuals are exactly that - a documentation outside the code. And while I'm very much in favor of adding these docstrings to the Python interface, I certainly don't want to remove the Python API reference wiki page (without a proper replacement, that is).Cjkjvfnby wrote:Its bad to have code and docs in different places.
That said, I do see the hassles with trying to maintain two sets of documentation (the one in the source code and the one on the wiki page). AFAIK there are tools which can compile reference docs out of the docstrings in Python code, if we can somehow incorporate such autogenerated docs into our wiki page, or at least put them somewhere where we can link to from the wiki page, that would be fine too.
Just don't provide the reference documentation for the Python API by Python docstrings only. I'm a person who prefers to have reference docs open in a separate (browser) window (or even printed out on paper!), not buried in some source code or only accessible by pop-ups in my IDE. I'm sure there are others like me out there.
adrain_broher wrote:I don't know what you're meaning with reference manuals, but most projects I use and maintain create their API and high level documentation from in code documentation. If it is about publishing the results on a web page/wiki it should be no issue in adding a make target for that.Vezzra wrote:Why? AFAIK that's actually "common standard", reference manuals are exactly that - a documentation outside the code. And while I'm very much in favor of adding these docstrings to the Python interface, I certainly don't want to remove the Python API reference wiki page (without a proper replacement, that is).
Cjkjvfnby wrote:Documentation support. You will not update documentation on wiki after API changes: "This page was last modified on 10 April 2012, at 16:55."
I don't know how to put generated docs to wiki, but I know how to make docs page on https://readthedocs.org/. If you want I can do some examples.
Vezzra wrote:E.g. this: https://docs.python.org/2.7/library/index.htmladrian_broher wrote:I don't know what you're meaning with reference manuals
This. What I definitely do not want is to just move all the API reference documentation into docstrings, which after all get specified and passed to Python in C++ code. Without further processing they are not of much use there, and most certainly no adequate replacement for the wiki page.adrian_broher wrote:most projects I use and maintain create their API and high level documentation from in code documentation. If it is about publishing the results on a web page/wiki it should be no issue in adding a make target for that.
But if we can devise a workflow by which we can generate reference documentation out of this in-code documentation, that's certainly fine, and far better than the current situation.
If you know a way how to generate wiki page content (which we could simply paste into our wiki) from these Python docstrings, that would be an solution I'd prefer.
Vezzra wrote:Of course that's a big problem, I won't contest that. But, as I said in my reply to @adrianbroher above, unless we can generate documentation we can provide elsewhere out of these docstrings, still better than having only the docstrings.Cjkjvfnby wrote:Documentation support. You will not update documentation on wiki after API changes
That could work too, although I'd prefer something we could paste into our wiki pages. However, if we can't do that, readthedocs.org is probably worth a try.Cjkjvfnby wrote:I don't know how to put generated docs to wiki, but I know how to make docs page on https://readthedocs.org/.