How does conan-docs implement its version switcher?

[hwhsu1231]

trafficstars

Problem Description

According to my understanding, Read The Docs will provide built-in Version/Langauge Switchers. However, it seems that Conan doesn't use RTD. Therefore, I wonder how conan-docs implement its version switcher?

Take CMake Documentation for example. It provides its own version switcher by using version_switch.js.

And it seems that the locally built documentation won't display the version switcher. How does Conan setup its version switcher?

Screenshots

[czoido]

Hi @hwhsu1231,

The documentation is generated using some scripts found here: https://github.com/conan-io/docs/tree/develop/.ci The series of commands to publish the docs can be found in this Jenkins pipeline: https://github.com/conan-io/docs/blob/develop/.ci/publish.jenkins This is not documented so it can be a bit tricky to generate locally the exactly same structure that we publish. You also can clone the gh-pages branch of the repo and get what's published in our website.

Hope this helps.

[hwhsu1231]

It seems that the version switcher is highly related to this Python script file, common.py. Can I ask how to use this file?

Take CMake Documentation for reference. This topic briefly explain how to setup its version switcher:

• Pass -A outdated=1 to Sphinx flag
• Put the version_switcher.js in the corresponding position

Since I didn't find common.py in gh-pages, I guess this file is used when building the documentation.

[hwhsu1231]

How does Conan-Docs insert these items into <dt>Versions</dt> when building?

[czoido]

How does Conan-Docs insert these items into <dt>Versions</dt> when building?

I can give you a couple of links that are relevant to generate that content: https://github.com/conan-io/docs/blob/bfb79aa755811cec5f8f6372729a524a81165c52/.ci/scripts/generate_documentation.py#L30-L31

https://github.com/conan-io/docs/blob/bfb79aa755811cec5f8f6372729a524a81165c52/conf.py#L49-L56

[hwhsu1231]

So it is related to this versions.json file in gh-pages branch, right?

However, compared to version_switch.js of CMake Documentation, this file only contains the following contents currently:

{"master": "latest", "release/1.3.3": "1.3"}

I wonder how it inserts such items?

[czoido]

So it is related to this versions.json file in gh-pages branch, right?

No, that file is outdated, it could be removed in fact, the first snippet I copied is the one that generates versions.json (they are imported from here) when we trigger the Jenkins job that publishes docs, then that info is passed to the html context