Move RTD docs to separate repo

All discussion on project related documentation including source docs, manuals, and tutorials go here.
Post Reply
User avatar
Ravenwing
Posts: 208
Joined: 02 Jan 2016, 02:51

Move RTD docs to separate repo

Post by Ravenwing » 22 Jul 2018, 17:19

So figured this is where we could discuss moving the docs. To summarize:

We want to start using more images with the documentation, but we don't want to muck up the main repo with binary files. We've moved image files over to a separate repo for now. This allows us to still link to them from the main repo, but this kind of screws with the documenters' workflow. We also can't add a logo and favicon from outside the main repo, but that's only a minor inconvenience.

The potential solution is moving ALL the docs over to that repo. From most standpoints, this is either better or won't affect anyone negatively. There are two main sticking points however. Automatic parallel versioning of the docs keeps relevant settings and other information with the appropriate corresponding documentation. As long as we add versioning this off to our list of things to do during releases, this is solved but slightly less convenient. The other annoying bit is that it's very convenient for devs to add settings entries to our documentation themselves while it's in the main repo. I'm afraid of devs basically ignoring the existence of documentation if we move them.

Also, weren't the docs supposed to also autogenerate documentation for the code specifically for the devs? How is this going to be done once we move things?

Anyway, that's basically where things stand. Thoughts on solutions and how best to overcome some of these things?

User avatar
psi29a
Posts: 4038
Joined: 29 Sep 2011, 10:13
Github profile: https://github.com/psi29a/
Contact:

Re: Move RTD docs to separate repo

Post by psi29a » 23 Jul 2018, 08:07

I thought it best to create a openmw-doc repo on GL, we can two-mirror it in GH too. This was at first just to host images for our docs to keep them out of openmw repo itself. The more I think about it, the more I think that it is ideal split out our documentation to another repo altogether as it would solve quite a few issues.

We wanted your thoughts first.

Loriel
Posts: 137
Joined: 28 May 2015, 00:44

Re: Move RTD docs to separate repo

Post by Loriel » 23 Jul 2018, 08:28

I am in favour.

From my perspective as an occasional producer of documentation, I think it will make my life easier.

But those who produce both code and documentation may find their lives more difficult if they have to contribute to two different repos, and keep them in synch.

Loriel

User avatar
Thunderforge
Posts: 438
Joined: 06 Jun 2017, 05:57
Github profile: https://github.com/Thunderforge

Re: Move RTD docs to separate repo

Post by Thunderforge » 23 Jul 2018, 15:54

The current system isn't working for people. While the proposed system isn't ideal (notably, it might result in documentation becoming out of sync with code), it seems like a better alternative to what we currently have.

Unless someone comes up with a better solution, I'm fine with going with this one.

User avatar
psi29a
Posts: 4038
Joined: 29 Sep 2011, 10:13
Github profile: https://github.com/psi29a/
Contact:

Re: Move RTD docs to separate repo

Post by psi29a » 23 Jul 2018, 16:06

Thunderforge wrote:
23 Jul 2018, 15:54
The current system isn't working for people.
Can you clarify? I thought it was mostly about images and binary content?

User avatar
Thunderforge
Posts: 438
Joined: 06 Jun 2017, 05:57
Github profile: https://github.com/Thunderforge

Re: Move RTD docs to separate repo

Post by Thunderforge » 23 Jul 2018, 16:17

psi29a wrote:
23 Jul 2018, 16:06
Thunderforge wrote:
23 Jul 2018, 15:54
The current system isn't working for people.
Can you clarify? I thought it was mostly about images and binary content?
I meant that it's not working as a process because we aren't able to add the content we want to effectively convey information. Sorry for making that ambiguous to seem as though it was functionally broken.

User avatar
Ravenwing
Posts: 208
Joined: 02 Jan 2016, 02:51

Re: Move RTD docs to separate repo

Post by Ravenwing » 24 Jul 2018, 01:33

Thunderforge wrote:
23 Jul 2018, 16:17
psi29a wrote:
23 Jul 2018, 16:06
Thunderforge wrote:
23 Jul 2018, 15:54
The current system isn't working for people.
Can you clarify? I thought it was mostly about images and binary content?
I meant that it's not working as a process because we aren't able to add the content we want to effectively convey information. Sorry for making that ambiguous to seem as though it was functionally broken.
Well there is the option of leaving just binary files on the separate repo and linking to them in the reST via URL. That’s how we have it at this exact moment. I am getting the feeling we’re all starting to lean towards moving the whole shebang to that repo though.

Psi29a, is it possible to have just the settings file in the main repo so devs can use it? I mean I’m sure there is, but with relatively little work? I don’t envision devs needing direct access to anything else. I believe that would solve all of our problems, even if that’s not quite an ideal solution. Unless we’re still generating docs using doxygen.

User avatar
AnyOldName3
Posts: 986
Joined: 26 Nov 2015, 03:25

Re: Move RTD docs to separate repo

Post by AnyOldName3 » 25 Jul 2018, 12:49

I'm still in favour of everything remaining in the main repo. Any sane amount of images is going to work out smaller than OpenMW's dependencies by a long way, so we're not really adding much to our disk space usage. If we're using a sensible folder structure, that's the main way in which images would clutter the main repo.

I'd rather all the docs were on a separate repo than they were split into pieces, though. If that's the route we take, there might be something we can do with submodules to try and keep things tidily synchronised, but I'm not exactly certain of the full power of submodules, so that might not be possible.
AnyOldName3, Master of Shadows

User avatar
psi29a
Posts: 4038
Joined: 29 Sep 2011, 10:13
Github profile: https://github.com/psi29a/
Contact:

Re: Move RTD docs to separate repo

Post by psi29a » 25 Jul 2018, 14:07

We've used submodules in the past and it was a PITA for developers to get their heads around which turned into another barrier of entry.

The problem is if we add binaries (images in this case) into the repo, then they stay there even after removal/deletion. With a few exceptions (ico, launcher, openmw-cs icons) the repo should be binary free. I've already went through purging binaries by re-writing history, thus reducing our repo size, about 10 years ago. I don't want to do that again, now that we have many more people contributing.

So as far as I see it:
1) binaries in an apart repo or images hosted elsewhere and link to them
2) sphinx/docs in an apart repo with images

I'm ok with either.

Post Reply

Who is online

Users browsing this forum: No registered users and 0 guests