how to make 2 columns with sphinx

Question

I want to make multiple columns on my documentation.

Globally, i would like to do something similar as this homepage, where there is 3 columns : one with current release, one with news & updates, and Basics.

When i search on google about multiple columns in Sphinx, i found about splitting a list in 2 columns which is not my case

On the wiki the only things i found with multiple columns is the table, but i don’t think this can apply here ?

Is this possible in rst files using Sphinx ?

Thanks a lot

Asked By: LudwigVonKoopa

||

Source

Answer 1

There are a couple of ways to do this, so either you find a three-columns-based sphinx theme (not that I know of any) or as @Steve_Piercy suggested you can create your own theme, which will probably be quite the task. However, you can instead use a theme of choice and simply adjust your .rst file content and overwrite your theme to display your content in 3 columns fashion. To do that you need some HTML and CSS though.

So first you need to create a test.rst with your content as html raw code like the following:

Test
======

.. raw:: html

    <div class="row">
      <div class="column" style="background-color:#aaa;">
        <h2>Column 1</h2>
        <p>Some text..</p>
      </div>
      <div class="column" style="background-color:#bbb;">
        <h2>Column 2</h2>
        <p>Some text..</p>
      </div>
      <div class="column" style="background-color:#ccc;">
        <h2>Column 3</h2>
        <p>Some text..</p>
      </div>
    </div>

Now that the content is ready, we create a style file for it under _static/custom_style.css that includes the following code:

/* Create three equal columns that floats next to each other */
.column {
  float: left;
  width: 33.33%;
  padding: 10px;
  height: 500px;
}

/* Clear floats after the columns */
.row:after {
  content: "";
  display: table;
  clear: both;
}

The last step is to add this style to your conf.py file in order for it to be added it to your theme. So in your conf.py add the following lines:

def setup(app):
    app.add_stylesheet('custom_style.css')

That’s it, now run and test. The output should look somewhat like this (depending on your theme):

Answered By: SuperKogito

Answer 2

Ok i finally found it :

you can use container keyword in sphinx/rst files to separate things

.. container:: twocol

    .. container:: leftside

        text on left column

    .. container:: rightside

        text on right column

And then in your .css file :

div.leftside {
  width: 43%;
  padding: 0px 3px 0px 0px;
  float: left;
}

div.rightside {
  margin-left: 45%;
  /* float: right; */
}

With this method, you can write everything you want in the container (image, links, text, … and it will be displayed properly.

Answered By: LudwigVonKoopa

Answer 3

This is a bit of an old question, but a potentially better answer to this question nowadays is to use https://sphinx-panels.readthedocs.io/en/latest/

That extension provides various components that you don’t have in plain reST.

Answered By: pradyunsg

Answer 4

One solution is to use the sphinx-design extension which is the successor to panels. Importantly, this does not require you to configure any html or css.

Answered By: Heberto Mayorquin

Answer 5

I am not allowed to add a comment to the accepted solution from LudwigVonKoopa but there is the question how to end the two column setting.
Additionally to the accepted solution and based on the answer from SuperKogito, I added this to my css file:


/* Clear floats after the columns */
div.after {
  content: "";
  display: table;
  clear: both;
}

This allows to end the two column part with

.. |space| unicode:: U+0020 .. space

.. container:: twocol

    .. container:: leftside

       Left side text

    .. container:: rightside
     
       Right side text


.. container:: after

   |space|

This does not generate a line in the html output but it ends the two column part.

Answered By: le_audio

how to make 2 columns with sphinx

Question:

Answers: