Documentation: please help write the docs!

(Frédéric Devernay) #1

In the official Natron documentation, I marked as “(empty)” the sections that need to be written.
If you feel like writing one of these sections, please go ahead!

The documentation uses reStructuredText: these are text files with little markup.

If you prefer editing with LibreOffice (or even MSWord), just keep the document simple (use styles for section headers, don’t try to format too much, etc.), and use pandoc to get a first working version in reStructuredText format. This file will probably require a few touch-ups afterwards, but it is usually a good starting point.

To send your contributions, you will need to:

  • fork https://github.com/NatronGitHub/Natron using your github account
  • on your fork, create a branch from the RB-2.3 branch (do not use the master branch), and give it a name like “documentation-keying” if you are ghoing to write the keying doc (which we really need)
  • to add your doc, you can either:
    • clone the repository to your computer, edit and add files, commit your changes locally (the github desktop application is easy to use), and then push your changes
    • or edit these directly on github, see tutorials-hsvtool.rst for example (you will probably need to fork the repository first, see below), and click on the pencil icon on the top right. You have the text view and can get a preview by clicking on the preview tab on top.
  • then you submit a pull request to the main repository with your branch (there is a button for this when you view your fork on github), and the Natron maintainers can either accept it as it is, or ask for a few modifications.

more details in http://natron.readthedocs.io/en/rb-2.3/guide/tutorials-writedoc.html

1 Like

(Omar Brown) #2

I will tackle the keying nodes but i can install or fork any GitHub stuff to my laptop because it belongs to my university.

I will use word and Pandoc to convert.

0 Likes

(Frédéric Devernay) #3

You don’t need to clone your fork to your local hard drive:

  • create your rst and png files locally (using pandoc for example)
  • fork Natron on github
  • in your fork, create a new branch from the RB-2.3 branch, as explained here: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/ , select that branch, and browse to the documentation at Natron/Documentation/source/guide
  • click “upload files” on top-right, or edit an existing file by clicking on it
  • then create a pull request
0 Likes

(Omar Brown) #4

Fred,

Is this the link that I need to fork at https://github.com/NatronGitHub/Natron. I have still a lot to learn about Github.

1 Like

(Mikhail) #6

Hi, I find some difference in documentation and my experience
in doc: (page 588)
#Set the After Project Created/Loaded callbacks
NatronEngine.natron.setOnProjectCreatedCallback(“myCallback”)
but in my project works
NatronEngine.natron.setOnProjectCreatedCallback(“init.myCallback”)
and
next plaсe don’t remember the page but may be example for setup project that you shered some years ago:
def addFormats(app):
app.addFormat(“Urfin2 2130x870 1.0”)
app.addFormat(“Urfin 2100x858 1.0”)

def Project_Callback(app):
app.getProjectParam(‘autoPreviews’).setValue(False)
app.getProjectParam(‘outputFormat’).setValue(“Urfin2”)
app.getProjectParam(‘frameRate’).setValue(24)
app.getProjectParam(‘frameRange’).setValue(1, 0)
app.getProjectParam(‘frameRange’).setValue(30, 1)
app.getProjectParam(‘lockRange’).setValue(True)

I can help you with documentation, but I have few time. Can you write video about how correct clone repository, how change some thing in doc and how can i correct send you pull request?
I think it will be helpfull for many people
Thank you!

0 Likes

(Mica) #7

There is plenty about this subject already, including github’s own documentation. You can do it entirely in your web browser with githibs edit functionality.

0 Likes

(Mikhail) #8

thank you! It is a very simple
I add some pull request about init.py

1 Like

(Ian Meredith) #9

I would be happy to add a useful and perhaps huge contribution to the Natron documentation in terms of usability and enjoyability, albeit with a caveate or two.

I should explain that I am today a professional technical writer and digital media artist/developer with my own personal licence for the industry leading tech’ authoring software Madcap Flare ( I know - it is not OpenSource but it is awesome. At £1500 or so was not an insubstantial purchase… but it really is the dog’s bollocks ( a British expression one may have to Google - Anything described as bollocks is rubbish quality, a useless product, or a ridiculous claim - BUT conversely, if it is described as the Dog’s Bollocks, there is nothing better! ). For any interested I have included a fuller background at the end.

Anyway I digress! I am about to learn Natron and the documentation looks comprehensive but not particularly navigable or engaging; (it seems a feature of Opensource that UI and documentation tend to fall behind commercial offerings). I am totally up for taking that content and using the industry leading toolset of Madcap Flare to createa website not dissimilar to 3DS MAX Documentation

  • Caveate 1: I am unsure I have the time to maintain such a site if updates are large and frequent, but my understanding is that Natron development is sadly pretty much dead - without any sign of an emergent replacement. Is that correct? If so then any updates would be infrequent and I would be happy to accommodate them. Of course, this is a deliverable distinct from the open source docs as unfortunately what I would deliver is not directly editable. That said if this took off I can see a way to enable contributor edit, but it would incur me cost and is easy but not entirely “technically trivial”, but then we are not a “technically trivial” userbase!

  • Caveate 2: Natron development may be dead but how “Dead” is Natron in terms of continuing users? If the view is that the party is over and everyone is moving on, clearly there is no point my doing this. However, if there are still many committed users who intend to use it for some years if nothing else materializes… well then it is worth doing.

Who the hell is this and why does he feel he has something to offer?
Being new here and unknown, I should probably establish some credibility!
Back in the '70s, yep I am that old, I completed degrees in architecture before jumping from the architectural ship to focus on the pioneering days of CAD and after writing my own extensions to the Prime minicomputer system “GDS”, still extant in PC form as “MicroGDS”. I leapt again from architecture to a career in software houses, first into CGI with a long deceased but again pioneering French company Thomson Digital Image aka “TDI”.

In 1989 they created the longest ever CGI movie “1789” . Today you may feel you could blink and miss it, but in those days with Silicon Graphics machines considered the dog’s bollocks (but pitifully slow compared to almost consumer laptops today), the rule of thumb was a £1000 a second!

Then I jumped again, into VR with Superscape - yes VR was an '80s phenomenon. When I hear the media talking about FB etc. as “VR Pioneers it cracks me up.” - From there I worked in both serious military flight simulation and desktop stuff like MIcrosoft Flight Sim before joinging LEGO as a concept developer… Like I said “Quantum Leap” seems sedentary to me!

BUT then I jumped again to what is now relevant… the tech author focus.

Thoughts? Anyone feel this something useful?

Best regards to all you Natron Users,

Ian

1 Like

(Mica) #10

I’m not a Natron user, but I think it would be really short sighted to move the documentation into a proprietary format with an application that not many can afford, and with a person who can’t commit to keeping it up to date, should development pick up again.

I don’t mean that as a knock on you, @MeridianCreative, your offer is generous, but I don’t see it as a long term benefit to the community. That’s just my opinion though, I’m sure others will disagree.

Also Madcap Flare… I’m a DITA / oxygenXML guy myself

0 Likes

(Ian Meredith) #11

I totally see your view. I am not suggesting that the documentation is moved into a proprietary format but rather that if these are the products end of days, a parallel delivery is created that offers a superior format that will help documentation usablility for what at present seems a product that is still valued but is dead in the water in terms of onward development. I don’t mean to be unkind but in my 35 years in the industry I cannot think of a singe example of a product in a similar position that again rose like a phoenix out of the ashes.

Perhaps a better documentation site might encourage an onward future.

Ah well, it was offered. No turn unstoned and all that. I will create such a site for my own benefit, but I guess best never to publish its URL.

0 Likes

(Mica) #12

The great thing about Free Software is that projects don’t really die as long as there is a copy of the source available. Anybody can get that code and start working.

You are free to publish whatever you’d like, keeping in mind that Natron’s documentation is licensed CC-BY-SA 4.0 at the bottom of the docs page: https://natron.readthedocs.io/en/rb-2.3/

1 Like

(Gord) #13

Let’s break your proposal into its two parts: an offer to write more engaging documentation, and a proposal to use Madcap Flare to author it.

I don’t think anyone would have a negative reaction to an offer to improve documentation. You are correct that documentation tends to lag everything else with most FOSS projects.

However, I share @paperdigits’ concerns about the authoring tool. Combine these statements:

and it appears to be a legitimate concern that the site would be unmaintainable if you were not able to keep maintaining it yourself.

I’m not a Natron user, but in the relatively short time it’s been included in discuss.pixls.us there has been a fairly high volume of posts, so it appears there is a lot of interest.

Personally, I think your offer is very generous, and I think it would become that much more generous if you are willing to use a FOSS tool to author the content.

1 Like

(Ian Meredith) #14

Thanks for the feedback. My point is that if I felt a FOSS tool could deliver to the level that I can deliver in the Flare product I would never have spent £1500 on the Flare product and someone would already have delivered the kind of professional finished documentation in that FOSS tool. The fact they have not kinda proves the point.

I am in complete agreement that if the community anticipates Natron continuing to evolve in any substantial way, to mirror the FOSS delivered documentation in a superior form carries an overhead which I am uncertain I feel that generously committed to. If alternatively this really is the “end of days” for the onward development then I would have felt there to be merit.

As it is, I am clearly not with the consensus on this, so will just create it for my own use as I think it will help my Natron learning curve to do so. I wish I’d never posted the offer now to be honest! :-/

Ian

1 Like

#16

Don’t be discouraged. Do what you think is best. There is nothing preventing you from doing this and sharing it, or not, on your own terms. What they are proposing is that using FLOSS authoring tools would help in the collaborative effort.

2 Likes

Natron development status?
(Frédéric Devernay) #17

Just keep in mind that the Natron doc is written in one of the most easy to handle format: text files.
Everything which is not pure text (formatting, images, links, etc) is using reStructuredText .
I don’t think the community should move away from that.

For his tutorials (HSVTool, Vector graphics workflow, Alternative Matte Extraction), @Blackvfx2018 sent us Word files, which were very easily converted to RST (using the pandoc tool, available on all platforms). I then had to fix a few glitches, and voilà. These tutorials look very nice.

One thing we should definitely do ASAP is to use a more standard theme for the docs, eg: https://sphinx-rtd-theme.readthedocs.io/en/stable/

The current theme doesn’t even have a search box.

3 Likes

(Ivan Gretsky) #18

What is the problem with switching the theme. Should be done easily in one line. Or am I missing something?

0 Likes

(Ivan Gretsky) #19

I made my own readthedocs playground for the Natron docs. Here is what I am getting with sphinx_rtd_theme.

Could somebody take a look and confirm it seem ready to merge?

3 Likes

Natron development status?
(Frédéric Devernay) #20

YES! thank you for that! Please file a pull request on github with these changes

3 Likes

(Frédéric Devernay) #21

@ivangretsky can you please file a PR? https://github.com/NatronGitHub/Natron/pulls
Please do it on the RB-2.3 branch.

Thank you

0 Likes

(Ivan Gretsky) #22

Sorry for a delay. Was away from the computer I could do it from. Will try to do it ASAP.

0 Likes