Documentation

[wclyffe]

I was wondering about the best way to produce the documentation.

Sphinx seems to be the best fit. It is using restructuredtext, which is similar to markdown. It can generate docs directly from the docstrings in the code, and obviously from whatever file you feed it. Sphinx can also output to html, pdf or even epub.

Besides ReadTheDocs.org can host and update directly from the github repo.

So, I took the opportunity to convert the current documentation to sphinx / restructuredtext to see more clearly what it could look like. (There's many themes you can choose from, or even make your own). It is still rough around the edges (some links, and other things are not correctly formatted yet)

Below are some screenshots of different screen resolution (the theme is responsive)

Oppinions?

[nortikin]

@wclyffe thanks. but first of all, it is needed to support images of nodes, if we create complete wiki. more over, we need to stop supporting addones wiki on official blender site http://wiki.blender.org/index.php/Extensions:2.6/Py/Scripts/Nodes/Sverchok and bring all to one place. But i not see direct benefits

[wclyffe]

@nortikin I must say that I didn't looked at the blender wiki site. In general (and that is for all the other addons), it is a bloody mess and not up to date. Usually, the best info is on the blog/site of the addon or blenderartists. I converted only what was in the docs folder, so there's was no images. But that's not a problem to have images in the sphinx documentation. I understand that there's a need to have documentation for all the different nodes (with examples!) For me, the benefits are :

• it is easier to update as it is all in one place
• it is text and images files in the repository -> no need to edit wiki pages and it is under version control
• you just need to make a link to the docs in the blender wiki (it is always up to date)
• the documentation is structured, on the blender wiki it one very long page
• you can document the code -> that's great for new developpers
• you can make a pdf of the docs (a user can access the docs even without internet connection)
• it is easier to collaborate, as it is just like for the code

[ly29]

Good documentation is really needed. I look forward to writing it.

I think there will be some nice surprises for all of us what the nodes the code can actually do.

[ly29]

I think it would be very nice if you could open the documentation for the active node in a browser directly via a help button in one of the panels. This is a bit down the road of course...

[wclyffe]

About the help button: I think It could be quite straightforward. With a custom attribute on each node and a class method to compose the url to the relevant doc. It could be even be done with some sort of naming convention, and then mirroring the categories in the code and the docs

[zeffii]

my favourite doc theme! I think the Blender docs are getting this treatment too, soon, but it is hush hush.

how does it fare with the table located in vector math node? I'm not going to write restructured text, it's GFM or pure markdown all the way.

rightclick node:

• view docs html
• view docs pdf (page)
• view source (copy)

[wclyffe]

@zeffii Restructuredtext: I thought too that it would be a pain, but the syntax is not that different than markdown. And it is way easier to inter/cross link between pages. To ouput one document from several markdown files is not really straightforward. Furthermore, sphinx is made for documenting python code : there's some facilities to extract the documentation from the docstrings directly.

And here's the table:

[wclyffe]

With this, you can get something like that:

[enzyme69]

Jimmy may be interested to write too.

[zeffii]

@wclyffe cool, i'll use Google style docstrings then!

[nortikin]

So, lets voting for variants. I see there is Sphinx solution, but also blender wiki page. What we need more?

[nortikin]

and i have to understand how to deal with images there

[ly29]

I think the best idea is to make a test documentation for one node and show how it looks.

[zeffii]

I think the blender wiki page should have a simple link to these documents here, and a full PDF link of the most up to date. People will prefer a link to nice documentation than reading the current implementation of blender wiki, no doubt about it.

[zeffii]

updating docs is much more likely to happen (correctly) if it's only necessary to update in one place.

[ly29]

@enzyme69 As the defacto English documentation for sverchok your help would be great.

[wclyffe]

I'll push my local branch then as it seems that there's some interest.

• First if some of you are using windows, I have to update some stuff so you can build the docs locally.
• I'll make an example with some images
• And I have to check the config to allow the auto-build by readthedocs (html +pdf)

[wclyffe]

In the meantime, if you want, you have a look at:

• RestructuredText Primer
• Sphinx Markup
• Sphinx/RST CheatSheet

[zeffii]

yes, i'm on windows :)

[zeffii]

pandoc --from=markdown --to=rst --output=README.rst README.md

please implement that, I don't think I can spare the extra attention span of learning rst.

[wclyffe]

• Problem is : sphinx don't understand markdown.
• The way sphinx build the html (or pdf) is built-in. I didn't implemented a thing. I just make html, and it's done.
• Pandoc markdown isn't github flavored markdown, you can use GFM but it is missing features
• Pandoc convert on a file by file basis.
• There's no way to specify an image size in markdown.
• As far as I know, there's no straightforward way to link between different files in markdown
• You could perhaps write a draft in mardown, convert it to rst and then edit the rst to add the missing stuff
• You could perhaps somewhat automate that with a parser, regexes, perl.... but I don't think I really want to go there..., but you are welcome to try.
• You would still have to use rst to pull the docstrings from the code
• From experience, pandoc pdf output from markdown isn't really predictable. You would have to convert first to latex, and then massage that a bit...
• RST is really close to markdown, I would think you are smart enough to pick up rst in no time.

[zeffii]

debating this would take more effort than learning rst.

[wclyffe]

Wise words :-)

[enzyme69]

Is this RST? http://en.wikipedia.org/wiki/ReStructuredText

Let's make it that so each node in Sverchok is explained really well, just like in Houdini.

• One click of a button take user to the guide (awesome)
• And examples can actually build and load some Node examples => I don't mind doing something like this. Could be nice.

[enzyme69]

[enzyme69]

Of course, it will also be unique-ly Sverchok. If this Add-On really embraced. It's a new language, the way I think of it. Alien for many who never use procedural workflow, parametric, or node, or even code.

[wclyffe]

Yes that is RST. But the examples on wikipedia are quite succinct. For example, an ordered list can use 1. just like in markdown.

The workflow is effectively quite alien for most users. And good accessible documentation and examples are necessary to get going

[enzyme69]

Dealga is a fan of on-the-fly markdown.

[zeffii]

I don't really have a problem with RST, i've read the specs now.

but in MD you can

• specify paths to local files [linkname](../../foo/bar.html)
• specify image size, MD respects inline HTML.

[wclyffe]

Image size in markdown : I didn't know about that workaround. Path to local file : I knew about that one. Where rst is different is that it builds a table of content, and you can make reference to any item in it. You could say that rst is a middle ground between tex and markdown

[zeffii]

our docs will look and read nicer than houdini's. but only if:

• we don't mix themes for screenshots.
• the default blender theme is crap for contrast. complete crap. it's dark and mirky - it should be avoided (or all screenshots should use it)..
• use a house style for illustrations (line thickness, colours, dash types, polygon colours)
• use consistent 3dview theme too

For me the key is consistency. Maybe i'm finicky, but it shouldn't be blatantly evident that multiple people write the docs. The docs should be personable not personal.

[enzyme69]

Yes, totally agree.

[wclyffe]

And image size is now completely irrelevant... I should read the docs more carefully:

    As a responsive style, you should not set a height and width to your images.
    Wide tables will add a horizontal scroll bar to maintain the responsive layout.

Stupid me! But curious about what that will do to the latex-pdf output

On consistency : I agree as well. Perhaps we should have a blend file in the repo with sane defaults that we could use for screenshots?

[wclyffe]

I just pushed my local branch and made a pull request.

To build the docs, just run make html from the docs directory. Then, if all goes well, open docs/_build/html/main.html in your browser of choice

[nortikin]

windows is evil

[ly29]

Realistically speaking I guess there will be a lot of proofreading of what I write in the documentation...

[nortikin]

a looooot of work

[zeffii]

Dont warrry you text will by edotted myrceloosly.

[nortikin]

))

[wclyffe]

Does the building of the docs work for all of you?

And it seems that the branch has been merged into master. If so, we should perhaps delete the sphinx-doc branch to avoid confusion.

[zeffii]

i got a make error

C:\blender_trunk\2.71\scripts\addons\sverchok\docs>make html
Running Sphinx v1.1.3
loading pickled environment... not yet created

Theme error:
no theme named 'sphinx_rtd_theme' found (missing theme.conf?)

but that file is located there, so it's a path thing i guess

[wclyffe]

Ok i'll try to have a look. I generated the make.bat file in a dummy project as an afterthought. So something could be borked in there, but since I can't test it...

[wclyffe]

Ok. It is a miserable fuck-up on my part. The theme folder was symliked from a clone of the original. So when I pushed my branch, there was effectively nothing in the theme folder. See https://github.com/nortikin/sverchok/blob/master/docs/_themes/sphinx_rtd_theme. I will fix this asap.

[wclyffe]

In the mean time , you can edit https://github.com/nortikin/sverchok/blob/master/docs/conf.py#L113 tohtml_theme = 'default' and comment out the next line with the theme path

[wclyffe]

Should be fixed by the new commit

[zeffii]

I can confirm this makes very pretty docs :) :+1:

[zeffii]

i hope the download zip gets these precompiled

[zeffii]

the scripted node doc has an embedded image, it doesn't show up. I hope to find a nice rst highlighter for sublimetext.

[wclyffe]

Currently the zip doesn't contain the compiled docs, but I could add that to travis But you can get the docs compiled(html + pdf) by readthedocs.org on every commit or release easily. And they host them for you. (and they are versionned)

But before thinking about distributing the docs, they should be of reasonnable quality, not perfect obviously, but at least covering the essentials.

Embedded image : what I did was still really rough around the edges. I didn't do anything about the links' formating. It was just a test to see was sphinx docs could look like and if people were interrested

The image should be in the images folder (or somewhere under the docs folder), and then you can reference them absolutely : .. image:: /images/file_name.jpg . The root / is the root of the docs folder. Or relatively ../img_folder/file.name.png for example

And we should use PNG or another lossless format

[zeffii]

.gif can be highly optimized for short animated examples, else .png