Proposal: Integrate forum and samples to the API reference

Serengeti (Rhino WIP) Developer
1

Hello,

I would like you to consider a problematic of 3D designers who find documentation and information of SDK for program Rhino and Grasshopper for experimental solutions or specific tools.

I’m talking here about 3D users who are not professional developers, just users who can open IDE, link the SDK and use it.
I’m not talking here about writing plugins like VisualArq or T-Spline. I’m talking here to playing with RH and GH programming in an easy way.

And I would like to propose to the voting community a minimal and simple help solution

Today, what we have?:

  • A good SDK in different languages,

  • Some good IDEs.

  • The Rhino Developer Docs site with:

    • A good place to start but for general purpose.

    • Some good code examples but without explanation like the Rhino Github samples repository

    • Some videos that may be more detailed.
      In this case, english videos tutorials are very restrictive because a lot of people can read on forums or english documentations (with or not with automatic traductions tools), but listen and understand an english speaker is very most hard.

    • And the API references site that don’t contains more information than the intellisense of editor can give us

  • This forum and the old Grasshopper forum that probably contains all the information we need for development but drowning between a multitude of messages. In this case the tags and categories want to help us but with approximate and variable results according to the good writing of the author (title, tags)

The problem:

All this is a good support, but if you exclude the restrictive case of English videos and information in the forum that drowning between a multitude of messages, understand the functionality of SDKs is not easy.
Also, in practice, we can open, the code editor, API references, the web page of the forum and juggle with them.

this approach is not practical and very long for 3d designers (especially for 3d designers because professional developers probably do not need to look for so much help).

Proposal to improve this:

All is in the title ! “Integrate forum and samples to the API reference” :slight_smile:

image
image.png806×924 97.3 KB

Considerate the PHP manual, in my opinion, it’s the best documentation that exists.
I pass the aspects of this manual that are difficult to implement in Discourse, Sandcastle Help File Builder or Doxygen and I am interested in function pages. For exemple this page http://php.net/manual/fr/function.preg-match.php but others is same.

Traditionally we have function signature, short description, arguments description and the return type but with an official exemples/notes and contributing exemples/notes.
Everything is in one page: API, examples, help. I know that many professional 3D designers use two screens, in this case, a documentation / API similar to the PHP manual would be very powerful.

By analogy with the PHP manual, we have:

  • The traditional function signature, description,… is the Api references site

  • The official examples/notes are the Rhino Developer Docs site and the Github sample repository.

  • And the contribution examples/notes is this forum

So, how to integrate this in one page?

Discorde propose all we needs:

on the API side:

  • if you know a little Javascript, you know that is very easy to integrate an external resource to a page with a simple ajax request endpoint.

  • And if you know the documentation generators, you know that all can integrate custom scripts and template.

Result

With this, we can have on the API page all topics that are resolved, related to the function and order by the vote relevance response.

The integration of official codes samples can be done in the same way but I stop here the technical details.

It’s just to say: I looked for the relevance of my proposal, it’s very simple. I’m just a simple hacker and even me, i could do it. So efficent access to information is essential to engage users/coder and eliminate redundant topics. And above all, make development accessible under RH/GH…

thanks!

2 Likes
2

[for french users] Salut ! J’écrit anglais depuis peu, donc comme je viens d’écrire un pavé, si vous lisez des choses incorrects, n’hésitez pas à me le dire, merci !

5

Hi jmv-

Wow, there’s a lot to digest here! Thank you for writing this up. While I mull this over - and mull I will - I just want to make sure that @stevebaer, @will, @nathanletwory, and @Alain see this.

-Dan

6

I think it is a nice proposal, if we have resources to dedicate to setting this up I don’t really see why we wouldn’t.

7

I would like to make sure I understand the essence of your proposal. Would it be doing justice to say that what you are proposing is adding two new sections to each API entry (regardless of programming language):

  1. Sample(s)
    and
  2. Community

…?

The links in the sample section would, in general, point to GitHub repos and samples within the site, is that correct?

By and large, the links in the Community section, would point to specific Discourse topics, is that correct?

If I’m understanding correctly - ignoring the technical details - this would largely be an improvement to the API docs only, rather than some bidirectional linking between the API docs and and Discourse (I realize you are proposing adding a plugin to Discourse, but I want to first better understand the primary improvement you are suggesting).

Given that the site is open-source, I am wondering would prevent you from mocking up something and submitting a PR? Even if you don’t have the time/inclination, it’s my hope that nothing would prevent this and I’d like to fix it if something is.

Thanks again!

1 Like
8

Hello @dan

Yes that’s right, we can say that.

I would like to say; "It’s not impossible." And we need to modify your help generator and I think it has to be done by McNeel.

Also, it’s hard for me to communicate with you, my English is bad. What it’s "PR"?

It’s not impossible, but it’s some works of course.
Integrating an external resource into a web page is easy, but I think the hardest part is: “Who and how to select the right external resources for an API page?”. Probably it needs testing.
For example, I see in this forum, the users take care to have a explicit title. But the “Solve” button is not really used. So links to the API must be made, ok, but by who?

  • The author of the message? Will they use it?
  • All members of the forum with a complex algorithm like Folksomony (Folksonomy - Wikipedia)?
  • Reserve to experts of Rhino SDK that can estimate the pertinence ?
  • …

Some use cases, maybe to motivate you! :slight_smile:

I see you are developing a GLSL node for Grasshopper. I dream today to use RH / GH for the same uses as Processing. And like the panel help in Rhino the quick video example is most explain than the text. For a 3d artists the exemple is sometimes all we needs for understand.

In my case, I sometimes need learn Rhino has new users and same me with RHv4 the first question with your software is "Where’s the command for …". A long time ago, I tried to simplify the user interface (GDI+ controls - Grasshopper). But at that time, it was too difficult for me. I thought Rhino 6 would improve that. Today, I can not wait anymore but now I can program in other languages, so I restart this project (Language for a beginner wishing extend UI Rh and Gh - Rhino Developer - McNeel Forum). My observation is that I spend a lot of time searching, like news users of Rhino "Where is the API function for …"

And all the others use cases that I can not imagine, but you understand the principle is to find the information we need.

Thank you for responding to this proposal.

9

Thanks for taking the time to get in touch :slight_smile:. I really like the suggestion to link the API, examples and questions/discussion together! We’ve worked hard over that last couple of years to make sure that all the necessary info is out there for developers to reference (i.e. guides, API docs, samples, etc.) but now the question is how to present this information to make is easy to use…

Pull request. But it doesn’t even necessarily need to be something as formal as that. It could just be a proof of concept hosted elsewhere on GitHub.

Currently, to generate the RhinoCommon API docs we run Sandcastle on RhinoCommon.dll and RhinoCommon.xml. We now use Doxygen for our C++ API docs and more recently I’ve experimented with customising the Doxygen output to make it fit in better with the rest of the site. We’ve also tried DocFX which looks promising, but we’ve not yet been able to generate anything useable.

If you (or someone else reading this) are willing/inclined to have a play around, then all these tools are open source and RhinoCommon is available both compiled and as source code (sure, this repository hasn’t been updated since Rhino 5, but it’s still very much useable for prototyping new documentation).

As @dan says, if there’s anything I’ve missed for anyone wanting to experiment with this idea, then please don’t hesitate to ask!

P.S. We also need to improve the search functionality to make it easier to find what you’re looking for.

1 Like
10

If your sites are set to allow Pull Requests then I think that a Mediawiki would be ideal for a “presentation site” utilizing page inclusion of anything related to a topic.

One could auto-generate page names (on the Mediawiki) based on the RhinoCommon & Grasshopper API since these pages covers just about anything Rhino. With those base-name pages on the Mediawiki one can go on with inclusions of whatever other info from other sources (including each API page itself).

In this way all the existing info out there can remain where it is while still being useful on the “presentation site” which brings it all together. Including any additional handcrafted info on the Wiki pages together with the inclusions.

Mediawiki also has all the Extensions imaginable, including Math formulas, Code highlighting, Multi language support plus Interwiki, aso.

The Mediawiki platform is quite useful, and it’s scalable enough for this use.

Does Discourse allow extracting threads or individual posts via API?

// Rolf

11

Hello @RIL !

Yes, via a REST API : https://docs.discourse.org

12

Thank you @will for this details.

Ok, maybe, but I’ve not a lot of free time.

What is your strategy? Want to improve the search functionality with an automatic function on the existing one or with an additional human classification action?

13

Since we are thinking big here I’d like to suggest a framework for solving this issue.

Possibly a scheme could be devised where video references could be placed on a centrally maintained list by anyone who might want a translation. Then anyone fluently bilingual in the source language (usually English) and the desired language who also has the time and inclination could provide the narration in the 2nd language. Perhaps the central site could also provide process guidance and useful tools to make the translation job easier. The translated video could then be put on the same site as the original.

Admittedly, this is just a skeleton concept, but perhaps it will get some concrete discussion going.

14

Not really a strategy, per se. I just want to make it clear that we know that the search in the Sandcastle-generated docs isn’t ideal. For example…

1 Like
17

Hello !

I would like to test a metadata server. The principle is simple, I extract the metatdatas of the documentation of the source codes (with Doxygen, docFx or other) in a format that I can translate in JSON (for example XML) and I expose it with a node-server API (via Json-rpc)

I got an XML from Grasshopper.dll or RhinoCommon.dll with docFx.
I got an XML files from OpenNURBS with Doxyfile.
I also got a JSON list of Rhino commands from your MadCap HTML export.
But I have difficulty extricating the google docs style from RhinoPythonSyntax. I tested the sphinx, doxypypy and pyment+doxygen but some informations is lost …

@stevebaer I read that you are the author of https://github.com/mcneel/rhinoscriptsyntax maybe you can help me!
Who tool can I use for extract the documentations and generate a XML (or JSON) file from your python files ?

Thank you

18

Sorry, no, I have the same problem with the cpp source :

  /*
  Description:
    Construct an arc from a circle and an angle in radians
  Parameters:
    circle - [in]
    angle_in_radians - [in]
  */
  ON_Arc(
    const ON_Circle& circle,
    double angle_in_radians
    );

/* ... Parameters: ... */ it is standard ?

19

I believe @will and @Alain know more about what documentation generation tools we use for each language than I do

20

Ah yes, the openNURBS doc comments are written in docjet syntax (from the Rhino 4 days). Here’s a rough and ready script that you can use to help Doxygen parse the comments.

Actually you reminded me… here’s my latest efforts to generate cleaner documentation for openNURBS using Doxygen and Twitter’s Bootstrap…

https://mcneel.github.io/opennurbs/6/df/d32/class_o_n__2d_size.html

It’s a work in progress, but I can definitely see potential to inject samples/discussions into the template. Reminds me of what Microsoft are doing with integrating GitHub issues into their docs.

21

That work fine, thank you @will !

Yes, I have see the API with Bootstrap, it’s clearer.
(For the visual aspect, I like http://typedoc.org/api but not for C )

My approach is really different.
I don’t search to have a visual data; I search to have a generic data from your multiple source (c, c#, py, discourse, md of jekyllrb, MadCad, etc…) in a same JSON format.
And a micro service (local or not) for serve this data.

Same as with LSP (Language server prototcol), the protocol don’t know if the data is for the a C or a Markdown file.

My motivation is not for work free but because i need have a clear Rhino interface.
And if an input box on the web or on the application can be give me this :

image
image.jpg559×726 115 KB

I’m happy ! (this view is very conceptual)

So I test the solution : Generic data + MicoService in background.

But today my difficulty (in addition to coding in C#) is to extract your resources in an exploitable format …

Thank you Will and Steve!

22

I think that would be amazing¡

23

Note: My previous message may appear off-topic in this proposal, but if we have data in JSON or XML and we know its structure. We can embed anywhere, without the language or technology constraints. (web page, Eto form, in a Makdown manual, …)

I know:

Probably a little harder … :slight_smile:

24

This sounds like a great idea :slight_smile:
The Clojure programming language has a pretty good community-driven documentation with lots of code examples - e.g. https://clojuredocs.org/clojure.core/interleave
I’m not familiar with any of this documentation-generation stuff, but the implementation is all open-source and might be interesting to look at for reference.