Hmm, that shouldn't happen for the ordinary ReST files. It can definitely be a problem when using extensions like autodoc, though. Still, as you say, rebuilding from scratch is generally pretty fast.
That's where I hit it most, using autodoc. I suppose I just got in the habit without remembering why.
Before you do too far down the path of converting to Sphinx, you may want to investigate implementing some custom directives and roles, since it's a lot easier to use those from the start than it is to retrofit them later. For example, rather than the current manually formatted list of bullet points which has no semantic markup, it may instead make sense to write something like: .. rest_api: Create Repository :method: POST :path: /v2/repositories :permission: create .. rest_param:: id :type: str unique identifier for the repository .. rest_param:: display_name :type: str :optional: user-friendly name for the repository .. rest_param:: description :type: str :optional: user-friendly text describing the repository's contents .. rest_param:: notes :type: dict :optional: key-value pairs to programmatically tag the repository .. success:: 201 database representation of the created repository .. failure:: 409 there is already a repository with the given ID .. failure:: 400 one or more of the supplied parameters is invalid There are a few advantages to using a custom directive like this: - you can also define a rest_call role that would let you write :rest_call:`Create Repository` and it would create a hyperlink for you to the appropriate rest_api definition. - you can define the formatting for the directive *once* and then all directives will follow it, instead of having to keep the formatting consistent manually - you can define indices and tables that summarise all instances of a particular directive (e.g. the module index and the full index in Python are generated that way) There's a tutorial on creating custom extensions in the Sphinx docs: http://sphinx.pocoo.org/ext/tutorial.html Cheers, Nick.
So glad you brought this up now. This is exactly the sort of thing I wanted to have nailed down before we really started down the path. I'll take a look this morning, thanks :)
-- Jay Dobies Freenode: jdob @ #pulp http://pulpproject.org | http://blog.pulpproject.org _______________________________________________ Pulp-list mailing list [email protected] https://www.redhat.com/mailman/listinfo/pulp-list
