Feature Request: Example mono repo code base

[jgarte]

I would like to request examples of the ways that sphinx-collections can be used in a real monorepo.

Maybe an actual example of a monorepo being documented.

For example, see the example project here which is pretty close:

https://github.com/backstage/mkdocs-monorepo-plugin/tree/master/sample-docs

[danwos]

I totally agree, we need some kind of a real-life example.

But in my understanding, I would not combine it with the keyword "monorepo", as monorepo does not tell anything about how the documentation is structured. It still can be in a single folder, or in multiple.

For me, it's more about central or distributed documentation, where distributed documentation has multiple locations, where doc-parts are stored. These parts can all be in a monorepo or in different repositories or just in different local folders or in a database and a script downloads them and creates files out of it or ...

So sphinx-collections is designed to give the user a free choice of how the documentation is structured. It just allows to collect the different parts into a joint, single folder-structure during the build.

But yes, a folder as an example inside this repo would be great. This could also be used then for test-cases :)

[jgarte]

Hi,

Thanks for the reply.

Instead of monorepo, what if we describe a large project directory that contains multiple related projects that follow PEP 420.

How would you handle such a project with sphinx-collections?

[danwos]

I would simply have a central /docs/ folder and multiple documentation under the related sub-project: /project_a/docs/.

All the subproject-docs are complete Sphinx projects and can be built on their own.

We use Sphinx-Collection on the central /docs folder to copy/link the subproject-docs together.

So for the build, it may be:

/docs
  - index.rst
  - conf.py 
  - project_a/
     - index.rst
     - .. other files 
  - project_b/
     - index.rst
     - and so on

[jgarte]

Thanks for the reply and info.

1. What are some examples of .. other files in your example above? static content such as css, images, etc.?

2. What if the large codebase looks like this and I would like to auto-generate an API reference with autodoc for all of the projects along with including README files which live in their respective project directories where the source code lives?

/monorepo
  - /project_a
      - README.md
      - src/
      - .. other files
  - /project_b
      - README.md
      - src/
      - .. other files
  - /project_c
      - README.md
      - src/
      - .. other files
  - /project_d
      - README.md
      - src/
      - .. other files

Would the docs folder structure still be as you stated (note that docs is at the same level as project_a, project_b, etc. source directories?

/monorepo
  /docs
    - index.rst
    - conf.py 
    - project_a/
      - index.rst
      - .. other files 
    - project_b/
      - index.rst
      - and so on
  /project_a
    - README.md
    - organizational_namespace/project_a/*.py
    - .. other files
  /project_b
    - README.md
    - organization_namespace/project_b/*.py
    - .. other files

[danwos]

other files can be anything. But mostly I was talking about md/rst files/folders storing other chapters. But for sure images and co. can be there as well.

source-files can be kept in the original folder. No need to copy them to the final "central" doc folder. Just make the project-folder aware to automodule by adding them to the Python-Path.

I don't know how you want to use README.md inside your Sphinx under /docs. That's up to you.

I'm also not sure in which status your above folder-structure is shown. Is it the one how it is stored in git? So the docs of project_a are really stored outside the main project_a folder? Or is it the way the final build folder under /docs shall look, but will not be committed to git. Sphinx-Collections creates a temporary folder structure during the build. So it mostly copies documents outside of /docs somewhere into /docs. So it doubles the files, but just for the build. Afterward the copied files under /docs get deleted again to keep the workspace clean.