Quickstart

Eager to get started? This page gives a good introduction to Sphinx-Ads. Follow Installation to set up a project and install Sphinx-Ads first.

A Minimal Sphinx Docs

To set up a Sphinx project, you need to do the following:

1. Install the Sphinx extension using the command:

   $ pip install sphinx
   

2. Setup the Sphinx project by running the following command (choosing the default config options) under a docs/ folder:

   $ sphinx-quickstart
   

3. Inside the docs folder, you should have the following file structure.

   

4. Create a JSON file named ads.json in your docs/ folder. The JSON file will contain the advertisement data. For example, you can store the following data in your ads.json file.

   {
   "advertisements": {
     "sphinx_needs": {
       "title": "Sphinx Needs",
       "description": "Sphinx-Needs is an extension for the Python based documentation framework Sphinx, which you can simply extend by different extensions to fulfill nearly any requirement of a software development team.",
       "target_url": "https://sphinx-needs.readthedocs.io"
     },
     "sphinx_needs_ent": {
       "title": "Sphinx Needs Enterprise",
       "description": "Sphinx-Needs Enterprise package provides enterprise specific solutions for Sphinx-Needs.",
       "target_url": "https://useblocks.com/sphinx-needs-enterprise/"
     },
     "sphinx_test_reports": {
       "title": "Sphinx Test Reports",
       "description": "Sphinx-Test-Reports shows test results inside Sphinx documentations.",
       "target_url": "https://sphinx-test-reports.readthedocs.io"
     }
   },
   "presentations": {
     "select-product": {
       "template": "sphinx_ads_default.html",
       "advertisements": ["sphinx_needs", "sphinx_needs_ent"],
       "selector": ".md-nav--primary"
     },
     "carousel": {
       "template": "sphinx_ads_default.html",
       "selector": "div.sphinxsidebar"
     }
   }
   
   }
   

5. In the conf.py file under your docs folder, you can set the values for the following options:

   extensions = ["sphinx_ads",]
   
   ads_path = "ads.json"   # path to the JSON file containing the ad data.
   ads_url = "https://example.org/ads.json"    # url link to the JSON data
   

   Note

   You can set the values for either ads_path or ads_url and not both in your conf.py file.

6. Create a layout.html file in the _templates/ folder under your docs/ folder. The HTML file should contain the following data:

   {% extends "!layout.html" %}
   {% block footer %}
   {{ super() }}
   {{ advertisement() }}
   {% endblock %}
   

7. Build the documentation project by running the following command in a terminal inside the docs folder:

   $ sphinx-build -b html ./ ./_build
   

8. You can open the HTML build files under the _build folder in your browser. The image below shows the index.html file in a browser.

   

So what did the above steps do?

1. First, we installed the sphinx extension and created a Sphinx project.

2. We then created the JSON file, ads.json, that will contain the advertisement data based on the recommended JSON data format.

3. Next, we configured our Sphinx project to use the sphinx_ads based on the recommended configuration.

4. We then created the Jinja template file, layout.html, which calls the advertisement() function in a Jinja block. We do not pass the layout name for the specific layout we want to use so the default layout provided by Sphinx Ads will be used. The function returns the advertisement HTML content we want to display in the user’s web browser. Refer to the advertisement() section on the configuration page for more information.

5. Finally, we build the Sphinx project and check the output in our web browser.