Call for volunteers: merge http://opticalenquiry.com/nuke/ into Natron doc

Hi,
I contacted Martin Constable from http://opticalenquiry.com, because his Nuke wiki was down.
Now it’s up again, and Martin kindly told me that we can use the content from his wiki for the Natron documentation. I think there is great content there, and most of it transposes to Natron.

We are looking for volunteers to:

  • take the text content (you can copy the wiki source)
  • produce new visuals using Natron
  • merge all this in the Natron doc.

Please answer to this message if you’re interested

3 Likes

Fred,

I would like to help the best way that I can.

Omar

1 Like

@Shrinks99, @Songtech-0912 what do y’all say?

@El_Artista I’m interested in doing so, will work through that over the weekend!

The main Nuke wiki is at http://www.opticalenquiry.com/nuke/index.php?title=Main_Page, right?

Happy to help out with this process once the new website is completed :slight_smile:

Prototyping is complete enough, code work starts soon! Gotta finish out the semester, one last project to complete!

I’ll begin once this is resolved: https://discuss.pixls.us/t/proposal-move-docs-out-of-natron-source-code-repo/24695. Basically, we need to move the docs out of Natron’s source code folder and into a separate repo. Otherwise, it would be very messy to work on the docs.

We won’t put the docs in a separate repo.

What’s the point? I don’t understand.
To edit the docs, just fork the repo on github, and edit these using the github web interface.

Reasoning for moving the docs out:

  • Keeping the docs in the Natron source code folder already takes up 31 MB, 40% of the repo’s current size. This will continue to get worse as the docs are expanded and content is added - it could take me 5 minutes to clone the Natron repository at times. It doesn’t just make the repo very heavy; it also means that any commits made to the docs are also made to the source code as well, and it’s therefore annoying to isolate the commits made to the docs as opposed to the source code.

  • The docs are in RST and Markdown, not C/C++ files, and are essentially a secondary codebase. We are mixing our concerns by keeping them together. By separating them, we can give our contributors a clear-cut view of what each is about and each is for.

  • Forking the repo on github to then work on the docs is very intimidating for many newer users of Natron, especially non-developers. After all, they already have to learn basically a new lanaguage (RST), which is difficult enough, but also needing to push their work to a codebase with 13,000 commits? In fact, this is the exact reason why I didn’t really contribute to the docs.

  • The docs are fundamentally not an essential part of Natron. We already keep the community plugins in a separate repo - so why not the docs?

We can always include the docs in the Natron repo as a submodule, for the use case of Natron’s built-in manual.

1 Like

Really, that makes things a lot more complicated, and I don’t see a single advantage. Documentation is only a small fraction of the repo.
Unless you fix the whole build system to make it the way you want (please send a PR), it won’t change.

1 Like

If so, that’s fine then. I’ll keep the docs repo as it is, and contribute to the docs accordingly.

@devernay I will be writing most of the new additions to the docs on https://hackmd.io/ though, and then moving it to Natron’s repo. It’s much easier to contribute on an essentially WYSIWYG editor than blindly editing RST IMO. Find it here.

Not a super ideal workflow but you do you. Have a look at RST Preview for VS Code or rst-preview for Atom.

I haven’t been checking discussions here much during last 3 months due to busy work, but I noticed this thread and another one about moving Natron docs outside of current Git repository.

This my opinion below can be well ignored as nonsense, as I haven’t been contributing anything to Natron. :slight_smile: …but, I think it would be better to have documentation in wiki type web platform where it could be easily edited directly using web browser.

I believe it would make easier to attract more contributors for documentation maintenance, as current method must feel quite difficult or troublesome for many of us. I setuped git and possibility to help with documentations long time ago, but if I would like to now add some information or create a new page I would need to “re-learn” what was the procedure to edit documentation rather than just login to website and write necessary information. I was informed that it would be possible also to make updates directly in GitHub site, but if I recall correctly it wasn’t easy to quickly preview the result.

I just wanted to share this opinion on this as many people can’t help with developing the complex software, but maybe could help with other aspects if those are made easy to jump in. I understand that for developers current method is very easy as they have all setuped and have the thinking which suits with it.

Still to add that of course I have no information how much documentation is used by Natron users, as I haven’t needed it myself because everything works mostly just like in Nuke.

(and I publicly admit that I did my last project compositing in Nuke rather than Natron, but in long term I would like to use Natron for work as well)

@devernay: I just made a pull request, added this section to the docs.

@Saku: I do understand that it is a bit a learning curve to contribute to the documentation, I think the main question is: If documentation would be moved out, who will care about maintaining it, keeping it free from spam bots, correcting things, etc…?

@Songtech-0912: I recommend using VisualStudioCode with .rst plugin.
Its a bit of a hassle to fork and clone the repo, setup the right conf.py file and install all the dependencies, but then its straight forward.

Good to know:
add to the .gitignore file in root of Natron folder:
Documentation/source/_build

BTW:
Universities should start teaching their students .rst file editing… its so much more relaxed than using a word editor…

1 Like

I think it would be better to have documentation in wiki type web platform where it could be easily edited directly using web browser

Wikis are lovely but they’re not the right format for software documentation, they’re also far more effort to set up and host than readthedocs. Wiki moderation is a whole lot more difficult compared to accepting and reviewing pull requests. Better templates and documentation on writing good docs would be a step forward.

Sure @magdesign and @Shrinks99. I fully understand that wiki is not the best for documentation and also current method is easy for developers. I felt it is quite difficult for non-programmers to support Natron, so everything is burden of few persons. Shouldn’t of course change anything by random request if that ends up having documentation maintenance totally neglected.

And nothing official should locate in 2 places to be maintained. That would be waste of time. Also I don’t know how many Natron users there are, so maybe it is not possible to get more contributors no matter where documentation Is is located.

Documents are anyway not the most important for keeping the software project alive and I’m very happy to see that it is maintained by rodlie, although I think very much alone. And Devernay seems to be keeping all in order. Even new version was released that I haven’t downloaded yet.

Long message again, but maybe my earlier post was more for myself to remember to start following this forum again and using Natron when getting some free time. :smile:

I agree that it is hard for non-programmers to get started on things like a version control system; indeed I am myself a programmer, and I still find it intimidating to contribute to Natron’s massive codebase!

I’ve hosted a simple editable wiki here: https://hackmd.io/@4Hwha1m4Tgm-uIGs2O6kwg/SkdrzENDO/edit. It is formatted with markdown which has a really simple syntax. I can merge this periodically into the main Natron docs, and there are a plethora of markdown to rst converters out there. If you have time to, feel free to add to the docs there.

Hi,
The hackmd.io as a draft of Natron docs is ok for me if it support images import/export.

I subscribed as “bonalex” to hackmd.io to contribute but it seems I don’t have write permissions could @Songtech-0912 invite me to the document.

@bonalex01 I’ve changed the permissions to allow for anyone to edit. Use this link now: https://hackmd.io/@Songtech-0912/SkdrzENDO/edit