Handle Multiple Repositories with Yaydoc

[imujjwal96]

This is a

• Feature request
• Bug report

Description

Currently, yaydoc can only generate and deploy documentation of a project hosted in a single repository.
Since there are multiple open source projects that are not limited to only a single repository, and have multiple subprojects that are dependent on a master project, we need yaydoc to be competent Enugu to generate a single static website for their documentation.

References:
#144 (comment)

[imujjwal96]

@pri22296 @Sch00lb0y Ideas?

[poonai]

I was doing research on this. we can clone all the repository doc and we'll create an index documentation page in which create a relation to all the documentation and we generate documentation using that

[pri22296]

I think we need functionality similar to http://docs.readthedocs.io/en/latest/subprojects.html. To achieve this, we may take a list of subprojects and their docpath's as input. we would copy the respective subproject's docpath as a subfolder of the master project's docpath. we'll also need to generate a proper index.rst(this might be left for now. for now let's expect users to fill the index.rst appropriately).
There may also be an relatively easy way for this. we might be able to use http://www.sphinx-doc.org/en/stable/ext/intersphinx.html . If intersphinx supports common search, it would make our work much easier. I'm not sure about it though. Let me research about it a bit

[imujjwal96]

A new repository for documentation or the master repository with docs deployed in gh-pages?

[imujjwal96]

What would be the flow now?
Should we first create a script and work with Travis implementation, like we did with Single Repository? Or should we keep both UI and backend in sync?

[pri22296]

I vote for the the first approach.

A new repository for documentation or the master repository with docs deployed in gh-pages

could you elaborate?

[imujjwal96]

Where should the documentation generated be published? :)

[pri22296]

The user would have to create a new repository to act as a holder project(like dev.loklak.org) and use yaydoc on the master project. Now building the holder project, would also clone all it's sub-projects and the generated documentation would be published to the ghpages branch of the holder project.

[imujjwal96]

Ok! So that means, the travis configuration will exist in the holder project. It will have the information about the repositories that will be cloned.

[imujjwal96]

What if a project doesn't have any master repository?

[pri22296]

User would need to create one. I can't think of any other way.

[imujjwal96]

if the user doesn't have a master repository, then the documentation repository will have the markdown for the start page.
Makes sense?

[pri22296]

Nopes.

markdown for the start page.

care to explain this part?

[imujjwal96]

Check this loklak/dev.loklak.org#2

[pri22296]

cool. Let's say i have 3 projects

• projectA
• projectA-sub1
• projectB-sub2

I would setup yaydoc in projectA and set projectA-sub1 and sub2 as the sub projects. In this case there would no need to create a holder project.

But if the three projects are totally unrelated, but i want them under a single domain, in that case a seperate holder project would be required. Makes sense?

edit
Now i got what you where saying. basically If a heirarchy exists, then the master repository would be the documentation repository. If it doesn't exists, a holder would be required. right?

[imujjwal96]

Yes!

[poonai]

can we have this as two issues like web UI implementation and Travis implementation? so that we can split the work. @imujjwal96 @pri22296

[imujjwal96]

As decided, we will first work on the Travis implementation. There is no need to create a separate issue yet.

[imujjwal96]

Let's start with the project that requires creation of a Holder repository. I have this organisation https://github.com/BrimeNotes We can use it for the development.

[imujjwal96]

#160 (comment)
@pri22296 did you check if intersphinx supports search functionality?

[pri22296]

I read about it and it seems search wouldn't work with it. but I didn't test it. I'll test it today.

update
No, intersphinx doesn't work here. It is only work cross-referencing components in sphinx projectc but the search wouldn't automatically search in the other projects.

[imujjwal96]

How should we start now?
Allow me to create a new repository in https://github.com/BrimeNotes with the name docs.
Let's first work on projects with docs assumed in the docs/ directory of each project
@pri22296 we should add the information about the sub-projects and their hierarchy in the yaydoc.yaml file

[pri22296]

Yep. Also the config.py file would need to be modified accordingly. I'll submit a PR for that by today. what should be the environment variable's format??
SUBPROJECTS = url1,url2 ?? or something else?

[poonai]

Since you both working on Travis implementation so, I'll work on WEBUI implementation. it'll boosts the development speed as well.

[pri22296]

As this is a big issue, I agree with #160 (comment) . Let's create seperate issues. Let's keep this issue as a parent issue for tracking overall development. This would help us avoid situations like #169 (comment)
@imujjwal96 @Sch00lb0y Your views?

[imujjwal96]

Situations like that wouldn't have raised if Scrums of peers would've been checked.
Anyway, i'm fine with separate issues.