Mimicking - Read The Docs

[Matthias Lübken]

Hi 

I am looking at Sphinx as our internal documentation tool. For my basic setup I want to have it look like http://read-the-docs.readthedocs.org/en/latest/index.html so I've started using https://github.com/snide/sphinx_rtd_theme which works fine. 

Now I want to mimic two main other features:

- The menu in the lower left with the different versions (from git branches and tags), downloads etc.

- The "edit on github" button

Any pointers how to configure / include these? As far as I can tell these come from readthedocs.org but I don't want to host my docs there.

Matthias 

[sphin...@michaelaltfield.net]

Hello,

I just published an article on how to host a sphinx/read-the-docs site on GitHub Pages using GitHub Actions:

* https://tech.michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1/

This email is an attempt to respond to this old thread asking how to host rtd (just in-case googlegroups doesn't understand the "In-Reply-To" Header I'm setting):

* https://groups.google.com/forum/#!searchin/sphinx-users/versions$20%22latest%22|sort:date/sphinx-users/huLkunvBy-8/BJgrWE3tQ8cJ

^ That thread was posted in 2014 and still hasn't received any responses. I found it when trying to set this up myself, which I found to be annoyingly opaque. So I wrote the above guide to help others achieve this.

> I want to mimic two main other features:
> - The menu in the lower left with the different versions (from git branches and tags), downloads etc.
> - The "edit on github" button

Part two of my guide (yet to be published) will cover adding the lower-left for accessing different languages, versions, and downloads.

It will also address the "Edit on GitHub," which I've also already documented on Stack Overflow:

* https://stackoverflow.com/q/62904172/1174102

I've managed to get the lower-left to be visible by setting 'READTHEDOCS' to 'True' in the 'html_context' dict() in 'conf.py' -- which I found only by digging through the code. Sadly, it doesn't appear to be documented anywhere. Similarly, I was able to populate the versions, downloads, and languages by populating 'versions', 'downloads', and 'subprojects' to a list of tuples in each.

I'll describe this more thoroughly in part two of my article linked-to above.

In the meantime, can someone please point me to the documentation that describes the above variables, if any? Specifically, I'd like to know about the internals of the internationalization and versions in rtd -- like why is 'languages' called 'subprojects'?


Cheers,

Michael Altfield
https://www.michaelaltfield.net
PGP Fingerprint: 0465 E42F 7120 6785 E972 644C FE1B 8449 4E64 0D41

[Jörg Faschingbauer]

On 7/18/20 1:47 PM, sphin...@michaelaltfield.net wrote:

> I just published an article on how to host a sphinx/read-the-docs site on GitHub Pages using GitHub Actions:

> * https://tech.michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1/

Let me add a "me too" here, referring to an article of mine (and a
companion article) that looks a the same topic from a slightly different
angle (no RTD specifics, for example).

Deploying Sphinx Generated Documentation to Github Pages:
https://www.faschingbauer.me/blog/2020/03/sphinx-gh-pages.html

Adding a Custom Domain to a Github Pages Project Site:
https://www.faschingbauer.me/blog/2020/03/custom-domain-gh-pages.html

Jörg
--
DI Jörg Faschingbauer
Linux und Open Source - Programmierung, Beratung und Schulung
https://www.faschingbauer.me
https://www.faschingbauer.co.at
j...@faschingbauer.co.at
Bergwirtstrasse 10
A-8075 Hart bei Graz
Tel. +43-664-5783814
UID: ATU64329756

[Robert Cohn]

Thanks for providing a guide. I am looking forward to part 2 with the description on how to create the versions in the lower left. Thanks.

[sphin...@michaelaltfield.net]

Part two of my guide to running your own Read the Docs site on GitHub Pages with their free CI/CD tools (including translations [i18n], versioning, pdf/epub, and the lower-left rtd menu) is now live:

* https://tech.michaelaltfield.net/2020/07/23/sphinx-rtd-github-pages-2/

[Stephen Finucane]

On Sun, 2020-07-19 at 09:17 +0200, Jörg Faschingbauer wrote:
> On 7/18/20 1:47 PM, sphin...@michaelaltfield.net wrote:
>
> > I just published an article on how to host a sphinx/read-the-docs site on GitHub Pages using GitHub Actions:
> > * https://tech.michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1/
>
> Let me add a "me too" here, referring to an article of mine (and a
> companion article) that looks a the same topic from a slightly different
> angle (no RTD specifics, for example).
>
> Deploying Sphinx Generated Documentation to Github Pages:
> https://www.faschingbauer.me/blog/2020/03/sphinx-gh-pages.html
>
> Adding a Custom Domain to a Github Pages Project Site:
> https://www.faschingbauer.me/blog/2020/03/custom-domain-gh-pages.html
>
> Jörg

Nice blog ++. As an aside, we (the Sphinx maintainers) would be more
than happy to work with anyone who wished to include this kind of
information into the mainline documentation (with links back to the
original resource of course). Some of our more recent tutorial content
is based off material from opensource.org and it's proven to be a good
addition.

Stephen

[sphin...@michaelaltfield.net]

Part two of this guide is now live:

* https://tech.michaelaltfield.net/2020/07/23/sphinx-rtd-github-pages-2/

If you don't care about how this works and you just want the quickest route to having a readthedocs.io-like documentation site hosted by GitHub Pages and built with GitHub Actions = GitHub's free CI/CD tools, you can skip the guide and just fork this repo:

* https://github.com/maltfield/rtd-github-pages

Here's a demo of the site, built from the above-linked repo

* https://github.com/maltfield/rtd-github-pages/tree/master

And If you want better support for the lower-left menu built-into the rtd sphinx theme, please +1 my PR here:

* https://github.com/readthedocs/sphinx_rtd_theme/pull/983

[Daniel Scott]

--
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/20200718114739.GA27401%40mail.michaelaltfield.net.