Tema per i documenti pubblicati su Docs Italia
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
demo_docs Admonition padding fix #34, usato path _static per semplicità di comp… Apr 5, 2018
docs-italia-theme Add admonition types May 23, 2018
js JS Cleanup Mar 7, 2018
sass Add admonition types May 23, 2018
tests Adds testing and hopefully a final fix for the empty toctree issue Mar 6, 2017
.gitignore Minor CSS fixes Feb 19, 2018
.travis.yml Adds testing and hopefully a final fix for the empty toctree issue Mar 6, 2017
AUTHORS Hidden language switch, fixed tables wrapping, updated license and re… Jan 29, 2018
CODE_OF_CONDUCT.md Hidden language switch, fixed tables wrapping, updated license and re… Jan 29, 2018
Gemfile fixing issue with compass conflicting with bourbon, and leftover on t… Dec 7, 2017
Gemfile.lock fixing issue with compass conflicting with bourbon, and leftover on t… Dec 7, 2017
Gruntfile.js Rimosso rework su JS perché RTD include i file da CDN Mar 2, 2018
LICENSE Hidden language switch, fixed tables wrapping, updated license and re… Jan 29, 2018
MANIFEST.in Ensure all static files are included Feb 28, 2018
README.md Update README.md Feb 15, 2018
package-lock.json Rimosso rework su JS perché RTD include i file da CDN Mar 2, 2018
package.json Rimosso rework su JS perché RTD include i file da CDN Mar 2, 2018
setup.cfg Configure package as py2, py3 universal wheel Sep 26, 2016
setup.py Merge pull request #37 from pdavide/l10n Feb 28, 2018
tox.ini Adds testing and hopefully a final fix for the empty toctree issue Mar 6, 2017

README.md

Join the #design channel Get invited

Docs Italia theme

This is the official theme for any piece of documentation hosted on the upcoming Docs Italia.

How to use Sphinx Italia on your documentation

  • Add the following line to your documentation requirements.txt file:

    $ pip install git+https://github.com/italia/docs-italia-theme.git
    
  • In your conf.py file, you'll need to specify the theme as follows:

    # Add this line at the top of the file within the "import" section
    docs_italia_theme = __import__("docs-italia-theme")
    
    # Add the Sphinx extension 'docs-italia-theme' in the extensions list
    extensions = [
      ...,
      'docs-italia-theme'
    ]
    
    # Edit these lines
    html_theme = "docs-italia-theme"
    html_theme_path = [docs_italia_theme.get_html_theme_path()]
    

Advanced Configuration

The theme's project-wide options are defined in the docs-italia-theme/theme.conf file of this repository, and can be defined in your project's conf.py via html_theme_options.

This theme has three different layouts included:

  • (default) documentation page layout, for documentation
  • home page layout, for the docs.italia.it homepage
  • landing page layout, for the docs.italia.it project homepages

Home page and landing page don't display any documentation content, and instead only relies on a special data syntax from Read the Docs to populate.

html_theme_options = {
    # To enable the landing page template, instead of the default documentation template
    'layout': 'landing',
}

Contributing or modifying the theme

  • Clone the repository:

    git clone git+https://github.com/italia/docs-italia-theme.git
    
  • If needed, install Sphinx into a virtual environment:

    pip install sphinx
    
  • If needed, install SASS:

    gem install sass
    
  1. Install node.js and grunt:

    // Install node on OS X
    brew install node
    
    // Install grunt
    npm install -g grunt-cli
    
    // Now that everything is installed, let's install the theme dependecies.
    npm install
    
  2. Run the main script to load a sample docs with the Sphinx Italia theme applied:

    npm start
    

This will compile static assets and watch files required for the theme to reload at runtime.

TODO: building a release, handling versioning system to enable automatic update on Docs Italia platform