.. _presentation: ############################# Right Presentation ############################# Set the Theme ============================= The default html theme for reST is somewhat lacking. The following console command, from within the project folder, will switch to the Sphinxdoc theme:: sed -i "s/html_theme = 'default'/html_theme = 'sphinxdoc'/" ./conf.py Modify the CSS ============================= After html pages are built the first time, the CSS for the theme can be modified for specific purposes. For example, let's disable the Sphinxdoc 80 pixel left and right margins. To create an override copy of the CSS which you can modify, enter the following console commands from within the project folder:: cp _build/html/_static/sphinxdoc.css _static/ touch _static/.gitignore .. Note:: The main ``.gitignore`` file could list :kbd:`*static` and :kbd:`*_static`, which would prevent git from tracking changes to the CSS. Adding a blank :kbd:`.gitignore` with the :kbd:`touch` command fixes this problem. You might prefer to edit this file interactively with nano, although you can comment out the margin command using sed:: sed -i "s/ margin: 0px 80px 0px 80px/# margin: 0px 80px 0px 80px/" ./_static/sphinxdoc.css Make index.rst Better ============================= Most of us do not start reading a book by staring at the Table of Contents, and most websites are made up of multiple pages or documents. The ability to hyperlink information so that it is accessible and understandable without referring to an index is a feature of the web. With this thought, the initial page :file:`index.html` can be replaced with something better as follows. Above the page heading of each document page, add a reference label:: .. _labelname: Then edit the document :file:`index.rst` in the project, and write the content for the front page. Embed \:ref\: links in the text to connect the site pages from the rewritten front page index. This approach is demonstrated in the :ref:`revised index ` for this guide. If your main documents are numbered, a Table of Contents can be generated by:: Table of Contents: ==================== .. toctree:: :maxdepth: 2 :glob: [0-9]* Borrow from Others ============================= `This GitHub repository `_ shows that the idea of publishing Sphinx documents in gh-pages has occurred to others. I like the elegant way that this project is presented: the project writes the project :file:`README.rst` file, which is the project documentation as a Sphinxdoc. `Other example websites `_ demonstrate the power of reStructuredText as a documentation and web development tool. Most of these sites have :guilabel:`Show Source` links to the original text of the pages.