Pulling in external sources in Gitlab

Skip to first unread message

Akikul Islam

Nov 1, 2021, 1:24:18 PM11/1/21
to sphinx-users
Hi There,

The basic problem I am having is that I have docs in several different projects in a private Gitlab.  I have started writing my docs in a project called "docs" and really don't want to remove the docs from where they are now (with their code) into my project.  
I think I have found something here which should work:

The thing is, I have no idea how to use it or install it.  Also, it is in beta and has not been updated.  Is there any other way?  Google'ing pointed me to people saying use "include" but I have no idea what that means.  

thanks in advance for any help


Nov 1, 2021, 1:55:51 PM11/1/21
to sphinx...@googlegroups.com
You received this message because you are subscribed to the Google Groups "sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/4dcc4fc8-daa6-4b50-af6f-e759af80034bn%40googlegroups.com.

Daniel Woste

Nov 2, 2021, 7:45:02 AM11/2/21
to sphinx-users

I'm the maintainer of sphinx-collections and ohh yes, there was no update since a couple of time.
Also the docs have no "installation" part. Sorry for this.

So here a quick "how to install and use it":

  1. pip install sphinx-collections (or install from github project)
  2. Add "'sphinxcontrib.collections'" to "extensions" for your conf.py file. See [1] for an example.
  3. Create a "collection" for git [2]:
    collections = { 'my_files': { 'driver': 'git', 'source': 'https://username:pass...@github.com/company/my_repo', } }
    Hint: Not sure if the auth part will really works like this for private repos.
  4. Create a rst file and use the files from the repo in folder "_collections/my_files/".
    E.g. ".. image:: /_collections/my_files/_static/project-logo.png"
  5. Build the project:
    1. cd docs
    2. make html
  6. Sphinx-Collections will checkout/pull the repo and store the files under "_collections/my_files".
    Then Sphinx starts its wonderful work.
  7. Done
I hope this already helps.

If not or you find any bugs, feel free to open an issue on the sphinx-collections bug tracker [3].


Akikul Islam

Nov 5, 2021, 7:04:24 AM11/5/21
to sphinx-users
Hi Daniel,

Thanks for the step by step.  I got it working.  FYI, I set up git with a private/public key so no auth set up needed in the driver itself

Thanks again


Reply all
Reply to author
0 new messages