Markdeep on the OF documentation


#21

great! let me know once you’ve uploaded that first draft.

as of the markdown file, I guess that it is generated by this script or a similar one


@arturo is the one that should know

best


#22

mmm, this is not what is written on the website actually.
http://openframeworks.cc/learning/08_other/contributing/
If the API reference is generated through doxygen, then the PR with the guideline proposal has to be opened on the OF repository, if the API reference is written in the markdown files, as written in the OF website, then the PR has to be opened on the ofSite repository. @arturo, what do you suggest?

A simple guideline would be, in my opinion, something like this:
for each method of the API, these fields are mandatory:

-name

  • description
  • syntax
  • parameters
  • returns

Optional:

  • example snippet
  • image
  • related methods
  • examples (with link to github) that use this method

I think it is better to start with a small list of mandatory fields that a method must have, to get to a bare minimum API reference faster.


#23

Just letting you know that I’m lurking and reading for now, once you have the template and we know which repo to work on (as well as how do we adopt classes? do we discuss that on GitHub as well?) shall get to helping/writing/working too :slight_smile:


#24

Well, I was kinda guessing. I think that those mandatory fields are already there but the ones you list as optional should be mandatory for the minimal API reference. Also, we should set what are going to be the minimal API clases and functions.

I think that this cheat sheet is kinda good place to start


#25

A short update on this front after the openFrameworks meetup in Berlin, where a bunch of people that write in this forum were attending.

The build system for the documentation works like this:

  1. The documentation for the API, visible here http://openframeworks.cc/documentation/ is automatically generated using doxygen, from the openFrameworks code. The python script generate markdown files. It is generated only when a new release is created. That means that if in between two releases, the signature of a method change in master, the changes are not reflected in the documentation.
  2. It is possible to commit directly in the markdown files, and that changes will be not overwritten when a new release is created.

During the meetup, @arturo (please correct any inaccuracy) suggested also that:
3) It is better to do not write too much documentation in the openFrameworks core, because otherwise the files become too long. Images and examples should be commited directly in the markdown files on the ofSite. Signature, parameters, short description and return values goes in the openFrameworks core repository, all the rest in the openFrameworks website repository.
4)In the past, any attempt do write documentation that was not bounded to the core failed, because nobody wanted to mantain the docs, and in general it was difficult to keep the doc in sync with the code.

Should we start making pull request versus master, containing commits that just add parameters, short description and return values? Maybe any person interested in writing the doc can “adopt” a module like @zach was suggesting?

I’m not part of the core developers of openFrameworks, and I do not want to force any direction, but I would like to help on this side and I have the feeling that other people, like @roymacdonald, @ayruos and maybe someone else on this forum have the same intentions.

Let’s keep this discussion going and let’s try to improve the doc of our beloved OF :wink:


#26

At the meetup I understood that svg is fine for the documentation, which is nice because it’s resolution independent.

Do we want images like these in the documentation? https://processing.org/reference/bezier_.html

In some cases we may prefer JPG or PNG, like here:
https://processing.org/reference/filter_.html

It would be great to include code + image (or text output) in the reference, I think it helps a lot understand how to use things. The examples in the examples folder are great, but often are not minimal enough (they don’t focus on how to use a single method).

I agree with @zach about organization. There’s one thing that confused in the past: the fact that when I search for something in the documentation, I find the same methods repeated many times. fullScreen is found under ofAppBaseWindow, ofAppEGLWindow, ofAppGLFWWindow, ofAppGlutWindow and ofAppRunner. Searching for triangle you find many different drawTriangle() methods? Could that be made that simpler?


#27

Yup, ready to help - I think someone should still take a lead on the project though, just to keep an overall eye on things documentation related and it would be nice if we first come up with guidelines on how we go about it wrt which repo to work with etc - basically things you’ve mentioned and asked about already but we start taking decisions on them, and maybe one of the core developers can help in that regard.


#28

@edapx great that you brought the subject to the berlin meeting.
I agree with arturo about not adding more stuff to the files. Actually I kinda hated when all the inline documentation was getting into the h files. There are some that are already over bloated.
I’d rather keep only the short explanation for each method, ie. what it does, what is each argument and what it returns, but we need to make sure that this is on all methods. And the long explanation, with images example code in this separate markdown file.

It would be great to have some kind of script that runs whenever a method or function is added or updated that informs whomever the “adoptive parent” is, thus making sure that proper the documentation is added/updated. If the class is still an “orphan” then the one that made the change gets notified. Maybe an issue, with special labels is opened for this. I guess that this is not that complicated, I could look how to make this work. Any suggestion for this or where to start from?

And, the other part would be properly organizing the documentation/learning sections.
I could begin to work on this probably at the end of this week.


#29

I can take care of writing a page with the guidelines in the wiki on github. In that page we will also list the maintainers for each module.

@hamoid , I think images are super helpful, let puts them in the markdown


#30

maybe a different markdown file for the maintainers?
this way we could show who is the current maintainer of each specific documentation in the ofsite, which could be useful. like if you go to the documentation of any class it could say who is the maintainer, so he could be pinged by anyone who finds a problem or wants to add an improvement.


#31

I’m happy to help with any porting or features (as the author of Markdeep).

-m


#32

Any news in this? Would love to help!
I remember that when I was starting to move away from Processing I was SO excited give OF a try but then the docs cooled me down :smile:


#33

@edapx did have any time to think about those guidelines?

By looking at http://openframeworks.cc/documentation/ofxSVG/ which is all empty, I was thinking that it would nice to see from the listing which documents contain no info, maybe with a tiny icon or a subtle color difference.

I think it would be motivating to see all those icons saying empty empty empty: we will want to get rid of all those icons by writing documents. Currently we can not get an overview, afaik, so we must click one by one each document to see which ones contain something interesting.

What do you think of such an icon or indicator?


#34

Unfortunately not, I’m pretty busy at the moment but it is on my list.


#35

I’m currently teaching myself how to use oF’s graphics facilities by recreating the examples put forth in the generative design handbook. As a side project for summer I am leaning towards doing tutorials and contributing to the documentation. I see a lot of potential in oF. I’m a decent note-taker and demonstrator, and enjoy explaining stuff because it helps me solidify my own understanding. Learning is perhaps my greatest joy in life and I want to spread the love. That said,

As a newcomer to the documentation is really sparse. Conversely, it’s offputting as a beginner to open the docs and get hit with the classes and their huge lists of (often empty) members.

example: ofColor has some >140 local template variables storing color ‘presets’. maybe this makes sense in some in the context of someone’s app but strikes me as obscure design. They’re also template types, meaning each function gets multiplied by however many template versions have to be created (float, int, double, vec2 and so on).
The reason I bring this up is that it obscures information and structure choices and makes the class use unclear with regard to the documentation. It’s an example of the ‘hard to grasp as a beginner’ sections, and it’s for a really basic type, arguably one of if not the first ones a newcomer will use in their app. Docs should strive for clarity and simplicity. As far as color is concerned, the important variables are PixelType r, g, b. Even if it’s just a matter of better member grouping, it’ll go a long way in helping people grok it.

I’d really like to help out and chip in (a lot of time) with docs, and eventually make tutorials on oF and it’s facilities & modules, as well as good C++ practices and design principles. I presume having a close familiarity with the documentation will better enable me to create clear ‘bigger picture’ style videos and be able to speak more candidly (without relying heavily on notes).

Something else that I have found to be really important for complete documentation is example code snippets that demonstrate how a function call gets used. http://en.cppreference.com/w/cpp and it’s predecessor http://cplusplus.com both do this and it’s excellent resource for newcomers and experienced alike to refer to. another good example of documentation is p5.js’s reference I’m willing to write a grip of these examples to the best of my ability.

Having someone experienced who can work with me will make this process go much faster and thus have a better chance of success. Ideally someone who is knowledgeable/experienced and willing to occasionally offer guidance and answer ‘noob’ (to intermediate) questions, to help me stay on track. I’ve hung out on the slack and irc channels to get a sense for the community here, but those channels are a bit of a ghost town.

If anyone thinks they can help out with that last bit and wants to team up with me for at least the next three months, please get in touch! You can find me on the slack channel or discord by the same user name #1199.


#36

Hi @figurehe4d , we’re all aware that there’s still a lot work to do in regards of the documentation. Although, this is a community driven open source project, for which no one gets paid, so in that sense you should be happy that this exists and it is shared. (And this community is very welcoming to anyone, so just post here if you have any kind of doubts :slight_smile: )
I would say that the best place to start is reading the ofBook. https://openframeworks.cc/learning/ scroll down a bit and you’ll find it.

cheers.


#37

As @figurehe4d I had not noticed but the reference for ofColor gets quite nasty with all the color presets.

I want to help here but I’m a bit lost.
@edapx @arturo @zach any clues on how to proceed on this? specially now that 0.10 is out.
Are we going to add the markdeep feature?
The templated classes in the documentation look a bit obscure, like ofImage_() and certainly it will confuse people if anyone tries to use it directly.
I now have a bit of time I can invest on improving some of these things.
best


#38

you can rebuild the docs from code by running:

the scripts that generate the markdown files live here: https://github.com/openframeworks/ofSite/tree/master/plugins/documentation/documentation/tools

the main script is: https://github.com/openframeworks/ofSite/blob/master/plugins/documentation/documentation/tools/documentation_update.py

the rest are utility classes and functions

I think the case of ofColor would be easily solved by adding a new section static variables probably also static functions by adding a new field to variables (functions already have it) saying if it’s static. if it is when generating the web, the templates should have a couple of new sections in the column on the left.

the plugin that generates the docs web pages is https://github.com/openframeworks/ofSite/blob/master/plugins/documentation/documentation/init.py and the templates https://github.com/openframeworks/ofSite/tree/master/themes/openframeworks/templates


#39

Also for templated classes i don’t think it’s such a big deal since it’s just for the constructors which most people won’t use explicitly but in any case it would be relatively straight forward to detect when a function is a constructor and if it belongs to a templated class remove the final _ as we do with the class name already


#40

Thanks @arturo
I’ll take a look during the weekend.
best!