Missing documentation for existing nodes

[portnov]

There are no corresponding .rst files for the following nodes:

2019-10-19 19:45:20,289 [INFO] docs_tests: Category viz: Tolerating unexistance of the documentation for the following nodes for now:
vd_matrix.py
viewer_typography.py
viewer_skin.py
vd_basic_lines.py
viewer_idx28.py
viewer_texture.py
viewer_curves.py
vd_draw_experimental.py
viewer_texture_lite.py
viewer_polyline.py
lamp_out.py
2019-10-19 19:45:20,291 [INFO] docs_tests: Category text: Tolerating unexistance of the documentation for the following nodes for now:
text_out_mk2.py
2019-10-19 19:45:20,294 [INFO] docs_tests: Category scene: Tolerating unexistance of the documentation for the following nodes for now:
blenddata_to_svdata2.py
obj_edit.py
BMOperatorsMK2.py
cache.py
objects_in_lite.py
particles.py
group.py
monad.py
curve_in.py
uv_texture.py
instancer.py
create_bvh_tree.py
particles_MK2.py
node_remote.py
2019-10-19 19:45:20,296 [INFO] docs_tests: Category modifier_make: Tolerating unexistance of the documentation for the following nodes for now:
join_tris.py
csg_booleanMK2.py
2019-10-19 19:45:20,298 [INFO] docs_tests: Category network: Tolerating unexistance of the documentation for the following nodes for now:
udp_client.py
2019-10-19 19:45:20,299 [INFO] docs_tests: Category generator: Tolerating unexistance of the documentation for the following nodes for now:
cricket.py
2019-10-19 19:45:20,301 [INFO] docs_tests: Category object_nodes: Tolerating unexistance of the documentation for the following nodes for now:
vertex_colors_mk3.py
sort_blenddata.py
object_raycast2.py
closest_point_on_mesh2.py
scene_raycast2.py
sculpt_mask.py
set_blenddata2.py
points_from_uv_to_mesh.py
custom_mesh_normals.py
color_uv_texture.py
filter_blenddata.py
2019-10-19 19:45:20,304 [INFO] docs_tests: Category matrix: Tolerating unexistance of the documentation for the following nodes for now:
matrix_array.py
2019-10-19 19:45:20,305 [INFO] docs_tests: Category number: Tolerating unexistance of the documentation for the following nodes for now:
easing.py
2019-10-19 19:45:20,307 [INFO] docs_tests: Category generators_extended: Tolerating unexistance of the documentation for the following nodes for now:
edge_split.py
2019-10-19 19:45:20,308 [INFO] docs_tests: Category script: Tolerating unexistance of the documentation for the following nodes for now:
multi_exec.py
sn_functor_b.py
topology_simple.py
sn_functor.py
2019-10-19 19:45:20,311 [INFO] docs_tests: Category vector: Tolerating unexistance of the documentation for the following nodes for now:
color_in_mk1.py
formula_deform_MK2.py
color_out_mk1.py
interpolation_mk2.py
formula_color.py
2019-10-19 19:45:20,313 [INFO] docs_tests: Category list_struct: Tolerating unexistance of the documentation for the following nodes for now:
slice_lite.py
numpy_array.py
2019-10-19 19:45:20,314 [INFO] docs_tests: Category bmesh_nodes: Tolerating unexistance of the documentation for the following nodes for now:
bmesh_obj_in.py
bmesh_out.py
bmesh_to_element.py
bmesh_analyzer_big.py
2019-10-19 19:45:20,317 [INFO] docs_tests: Category modifier_change: Tolerating unexistance of the documentation for the following nodes for now:
flip_normals.py
mesh_beautify.py
grid_fill.py
limited_dissolve.py
extrude_multi_alt.py
limited_dissolve_mk2.py
mesh_separate_mk2.py
triangulate_heavy.py
symmetrize.py
2019-10-19 19:45:20,318 [INFO] docs_tests: Category list_mutators: Tolerating unexistance of the documentation for the following nodes for now:
vd_attr_node.py
filter_empty_lists.py
2019-10-19 19:45:20,320 [INFO] docs_tests: Category analyzer: Tolerating unexistance of the documentation for the following nodes for now:
bvh_nearest_new.py

It is possible that for some of them the documentation actually exists, but file name differs. In that case documentation file should be renamed.

[vicdoval]

https://github.com/nortikin/sverchok/blob/b28_prelease_master/docs/nodes/analyzers/intersect_plane_plane.rst https://github.com/nortikin/sverchok/blob/b28_prelease_master/docs/nodes/analyzers/intersect_line_sphere.rst https://github.com/nortikin/sverchok/blob/b28_prelease_master/docs/nodes/analyzers/deformation.rst https://github.com/nortikin/sverchok/blob/b28_prelease_master/docs/nodes/analyzers/distance_line_line.rst https://github.com/nortikin/sverchok/blob/b28_prelease_master/docs/nodes/analyzers/bbox_mk2.rst https://github.com/nortikin/sverchok/blob/b28_prelease_master/docs/nodes/analyzers/distance_line_line.rst and maybe others, they are there, what is the problem with them? and about pulga_phisics.rst. I was in the 2.7 branch... i missed it no i try to add it in #2622 and Travis throws a failure. The node is on the alpha category but on the modifiers_make folder. I placed the docs on the alpha folder. Did I miss anything?

[vicdoval]

Or maybe I should ignore this tests by the moment?

[portnov]

Most probable problems are

• node file name is not equal to documentation file name
• node directory is not equal to documentation directory name

[portnov]

Aha, I see, under docs/ we have analyzers (note the s), but under nodes/ we have analyzer (without s)... probably there are other similar problems too.

@vicdoval you may add your node to known problems list (in the docs_tests.py) for now if you wish.

[vicdoval]

There is just one fail in #2622 that probably is due the analyzer 's', Do you want me to change the folder name or ignore it and leave it to you?

[portnov]

I'll rename the directory.

[portnov]

Renamed in b28_prelease_master.

[portnov]

@zeffii what should we do with alpha_nodes and beta_nodes? For other directories, there is 1-to-1 correspondence between directories under docs/nodes and under nodes; but we do not have nodes/alpha_nodes or nodes/beta_nodes. Should we remove corresponding directories from docs/nodes? Or...?

[zeffii]

@portnov i propose to drop those doc/directories .

I further propose the inclusion of some short-form documentation in the .py of each node that doesn't have .rst, maybe as a class property. Or maybe docstring extension..

node_doc = " some multi line info, formatted in some way that can be parsed "

class SvNodeName(....):
    ...
    sv_shortform_doc = """    """  #   node_doc

in which several things are made clear to the user

1.  this node is not very well tested ( feel free to help and provide feedback at the issuetracker
2.  known issues with the node (limitations, algorithm implementation details)
3.  a link to the development thread(s) / pull request that spawn the node
4.  a mention of the creators handle, optionally.
5.  a date of node submit
6.  what else?

I suspect few users take the time to read the docs, altho i think we provide a most convenient way to do so with the nodepanel / item / open documentation buttons. Perhaps an additional spawnable panel from the Rclick menu of nodes could show a small popup of "Node Info".

[portnov]

I've dropped alpha_nodes and beta_nodes under docs.

As for docstring... Well, ideally each node should have docstring, even those ones with documentation files — rst file is user documentation, docstring is more for developers.

But, as you can see, there are many nodes without any documentation. If anyone has enough time to write either docstrings or regular documentation for them, you're welcome! :)

[zeffii]

i'll do a proof of concept for vd_experimental , maybe :)

[zeffii]

docstring is more for developers.

i agree, and also disagree. I am becoming a big proponent of not separating documentation that way.

the bpy py console is massively unutilized.

>>> nodes = bpy.data.node_groups['NodeTree'].nodes
>>> n = nodes['VD Experimental']
>>> help(n)

# 1. bla...
blablabla
# 2. blablabl
blablablablablabal

etc.

ascii schema

would be awesome.

[zeffii]

but going off topic a little bit. i've been meaning to do some popup based documentation POC . this is good reason to do that today.

[portnov]

Technically, at sverchok loading time, we could read rst documentation and do for node in nodes: node.__doc__ = read_rst_documentation(node) :) not sure if it would be that useful, though...

[zeffii]

perhaps overwriting doc is a bit hardcore :)

>>> n.help   

would be a reasonable SvNodeCommon solution