white label functionality?

[John Ezekiel]

Hey guys,

I'm looking for a documentation library just like Sphinx. Only problem is, We are a software that is white-labeled for each of our clients.

Is there any support in sphinx for white-labeled products? For example, we have 5 products, named internally. All 5 of those products have aliases for each of our clients, so the doc generator should be able to support some sort of templating that retrieves their aliases from the database.

Is this possible with Sphinx now? Or will I have to roll my own solution?

Thanks!

[Gert van Dijk]

If I understand your question correctly, you have a situation like:

- productX with docsX/

  clientaliases:

  - client1: Red

  - client2: Blue

  - client3: White

And you want some rebranding based on an alias within a product.

I'm going to make some assumptions:

- The rebranding is only textual or theme parameters.

- Your documentation sources are in RST format (not Markdown extension etc.).

Given that, you could do some simple substitutions with rst_epilog [1].

Write lines in RST like:

  This is the documentation for |productx|. In order to use |productx|...

And in conf.py:

  rst_epilog = '.. |productx| replace:: Product X please_replace_me'

Run your builds with the parameter as variable to override in conf.py [2], example with both make and

sphinx-build approach:

  make SPHINXOPTS="-D rst_epilog='.. |productx| replace:: Red'" [...]  # make, other options and target omitted

  sphinx-build -D rst_epilog='.. |productx| replace:: Red' [...]  # plain sphinx-build, other options omitted

Alternatively, read an environment variable in conf.py and have set that accordingly for each customer,

but with the same command for all builds.

(Or, alternatively, have a red/conf.py in which you import everything from common/conf.py, but override the

rst_epilog variable. But I guess you wanted a more dynamic approach on the command line.)

For HTML/theme variables, use the -A option [3] instead, but that totally depends on your theme and the

amount of customization you put in there.

If you're looking for a way to produce output for each customer with a single sphinx-build command,

you may want to write a Python script that pulls the client-product-alias from your database and spins

up sphinx-build programmatically with a config override just like I did above. For inspiration on the

programmatic approach, I would recommend to look at how sphinxcontrib-versioning does it for building

for each version of a project [4].

HTH

[1]: https://www.sphinx-doc.org/en/2.0/usage/configuration.html#confval-rst_epilog

[2]: https://www.sphinx-doc.org/en/2.0/man/sphinx-build.html?highlight=sphinx-build#id2

[3]: https://www.sphinx-doc.org/en/2.0/man/sphinx-build.html?highlight=sphinx-build#id3

[4]: https://github.com/sphinx-contrib/sphinxcontrib-versioning/blob/920edec0ac764081b583a2ecf4e6952762b9dbf2/sphinxcontrib/versioning/routines.py#L173-L179

[John Ezekiel]

Amazing Detail, thanks!

Looks like it should do what I'm looking for. I'll report back!