Refactoring Sphinx files into directories

For larger projects, we'll need to use directories instead of simple files. It's common to have a project expand from a few simple files to a more complex structure, where the files are replaced by directories. In this case, we'll perform the following steps to refactor an RST file into a directory that contains RST files:

  1. Add the directory – implementation, for example.
  2. Move the original implementation.rst to implementation/index.rst.
  3. Change the original index.rst file. Switch the .. toctree:: directive to reference implementation/index instead of implementation.

We can then work within the implementation directory using the .. toctree:: directive in the implementation/index.rst file to include other files that are in this directory.

When our documentation is split into simple directories of simple text files, we can edit small, focused files. Individual developers can make significant contributions without encountering any file-sharing conflicts that arise when trying to edit a word-processing document.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset