3

The scheme is the following. There exists a package called foo (an API under heavy development, in first alpha phases) whose rst files are auto generated with sphinx-apidoc.

For the sake of having a better documentation for foo after those files are generated, there is some editing. In, say, foo.bar.rst there are some paragraphs added to the contents generated with sphinx-apidoc

How can I not loose all that information when a new call of sphinx-apidoc is made? And of course I want potential changes in the API to be reflected, with that manual information added being preserved.

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Jorge Lavín
  • 937
  • 8
  • 22
  • 1
    In one of my projects (which uses git), I keep a separate orphan-branch to keep track of all sphinx related changes. Then whenever we need to generate the documentation in html, I branch off from master, and merge the sphinx branch in. That ways, all changes related to sphinx are versioned, and any over-writes due to *work-in-progress* is avoided. – Anshul Goyal Feb 12 '15 at 15:36

1 Answers1

5

sphinx-apidoc only needs to be re-run when the module structure of your project changes. If adding, removing, and renaming modules is an uncommon occurrence for you, it may be easiest to just place the rst files under version control and update them by hand. Adding or removing a module only requires changing a few lines of rst, so you don't even need to use sphinx-apidoc once you've run it once.

Kevin
  • 28,963
  • 9
  • 62
  • 81