Proposal: Move Docs out of Natron Source Code Repo

Currently, Natron’s documentation lives in the Documentation/ folder of Natron’s source code. While this may be more convenient, it adds a lot of extra weight to the repo (31 MB after doing some tests), and makes editing the docs a lot harder for non-programmers.

Instead, why don’t we move the docs to their separate repo? Then, if we want to, we could always add the docs back into the main repo via a submodule.

1 Like

I don’t understand what’s a lot harder?

@devernay Essentially, I’m of the opinion that by breaking things up you create parts of Natron that can be worked on independently and more efficiently than lumping everything together.

Firstly, the very large repo size causes a lot of download time, especially under poor internet connections. Commits are also slow to make, because git has to synchronize something like 10,000 commits. Moving the docs out would at least partially resolve this problem.

Second, the docs are somewhat hidden from view by being in a subfolder of a repo. Getting them to a separate repo would help this.

You don’t have to download the whole repo, see git shallow clone.

That isn’t how git works, neither or pushing or commiting . perhaps if you’re on windows and there are a lot of files, performance will be bad.

1 Like

@paperdigits Yes, these are fair points. However, for the sake of separating the source code and documentation, which are for fundamentally differing functions, I think we should still move the docs to a separate repo.

1 Like

Sure, we just split the docs out for darktable, and I think its been working well for us.

1 Like

Would also be in favour of a separate repo, this way you can also assign different levels of access to the docs repo VS the actual project code so contributors can be added for docs write access but not the whole project. Bonus points for security or whatever.

As a complete non-programmer here on this list, I would need help as to how to get started. I have written tutorials before, but this repo stuff, I am completely lost.

Help a novice out. How can I convert my pdf docs to whatever this repo stuff is.

@Blackvfx2018 They need to be copy-pasted into plain-text RST format. RST (Re-structured text) is a markup language similar in function to Markdown (used here for formatting in forum posts!). In order to submit these text files we use git to ensure that the changes we make don’t overwrite anyone else’s work.

Happy to do a full walk-through of the process for you on Discord or something sometime, I’ve taught a whole bunch of people how to use git for basic tasks like this before and it takes about an hour. You need zero actual programming knowledge to be able to understand how to use any of it but IMO it’s a little tricky to get started with git (and the GitHub Desktop client) unless you’ve got somebody to show you the ropes. :slight_smile:

1 Like

@Shrinks99 This sounds like a plan. How are your weekend nights like? Saturday nights after 9pm eastern time is good for me.

Something like that works totally fine for me! I’ll be a little busy this coming week finishing up some stuff but any time after that is probably good? I know you’ve got lots of good stuff so having you able to contribute to docs would be great :smiley:

1 Like

Thanks. Just let me know when you are teaching on discord. I have to register for the site.

Here’s the link for the Discord community.

1 Like

also see the documentation on writing documentation https://natron.readthedocs.io/en/rb-2.4/guide/tutorials-writedoc.html

Also please remember that the doc is not a standalone thing, so splitting up the repos means more work for putting things back together and building the docs.
And frankly, there are not THAT MANY contributors to the Natron doc. I think we can deal with the relatively low volume of PRs for now.
There have been a few documentation PRs, and all have been accepted https://github.com/NatronGitHub/Natron/pulls?q=is%3Apr

Please write the f***ing doc, do your PRs, and if we get over 10 PRs per day we may consider splitting the repos. Thank you.

I had joined but looking for groups to participate

Do you have the source douments for these PDFs? What is the file format?

@paperdigits This is a link to my WordPress page called colorgrade13 at https://colorgrade13.wordpress.com/2016/12/14/natron-vfx-compositor-tracker-node/. I wanted to contribute my tutorial on Natron Tracker node that I created a few years ago. I should be able to convert it to a word doc and then to a plain text doc with the graphics extracted.

Acutally this tutorial was export out to a png file. I would need to find the original PDF doc to complete the project.

There have been a few documentation PRs, and all have been accepted https://github.com/NatronGitHub/Natron/pulls?q=is%3Apr

@devernay The most recent docs PRs are not being merged due to MacOS Travis CI build fails (see https://github.com/NatronGitHub/Natron/pull/612) . Could you please see what is causing those issues? Otherwise you might really have 10 docs PRs in one day that go unresolved :wink: