Pulp

Task #939

Updated by dkliban@redhat.com over 9 years ago

Documentation Each project should be added have a conf.py inside it's docs directory. conf.py should contain 

 <pre> 
 intersphinx_mapping = {'python': ('http://docs.python.org/2.7/', None), 
                        'rpm':      (("http://pulp-rpm.readthedocs.org/en/%s/" % rtd_builder), 
                                   None), 
                        'puppet': (("http://pulp-puppet.readthedocs.org/en/%s/" % rtd_builder), 
                                   None), 
                        'ostree': (("http://pulp-ostree.readthedocs.org/en/%s/" % rtd_builder), 
                                   None), 
                        'deb':      (("http://pulp-deb.readthedocs.org/en/%s/" % rtd_builder), 
                                   None), 
                        'docker': (("http://pulp-docker.readthedocs.org/en/%s/" % rtd_builder), 
                                   None)} 
 </pre> 

 `rtd_builder` can have a value of 'latest', '2.6-release', '2.5-release', etc. The value should correspond to http://pulp.readthedocs.org/en/latest/dev-guide/contributing/documenting.html#editing-the-docs 

 the version of docs that config is referencing.  

 When you want to reference docs of any of the projects mentioned in `intersphinx_mapping` just add the following code: 

 <pre> 
 :ref:`importer config docs <puppet:configuration>` 
 </pre> 

 The above example relies on 'puppet' being defined in `intersphinx_mapping`. It also relies on a label called 'configuration' existing in the puppet docs. 
 A list of all labels for a project can be found by using this script: https://gist.github.com/dkliban/683c3e9cdfc1ba884226/c8c3e0e10fef5dbe7525cd1b1137357e93862685 

 Save the gist as an executable called `inventory.py` and then invoke the following command: 

 <pre> 
 ./inventory.py --url http://pulp-puppet.readthedocs.org/en/2.6-release/objects.inv http://pulp.readthedocs.org/en/2.6-release/objects.inv 
 </pre> 

 The URL can point to any RTD builder. Each of our builders generates an objects.inv each time the docs are built.  

 If you don't see the label that you wish to link to, then you need to create one. A label can be created by adding the following tag: 

 <pre> 
 .. _label1: 
 </pre> 

 The above code will create a label1 that can be reference externally. If `label1` was added to the `puppet` project then it can be referenced with: 

 <pre> 
 :ref:`importer config docs <puppet:label1>` 
 </pre>

Back