Break up style guide into multiple pages

[bourque]

Change Summary

Overview

This PR splits up the sections of the style guide into their own pages. The Release Workflow is also moved from out of the style guide.

New Files

• Several new .rst files for each of the sections of the style guide

Updated Files

• style-guide.rst
  • Removed most of the content, and now instead including the individual .rst files are the content
  • Removed the Release Workflow section, as it is now outside of the style guide

[bourque]

While the sections of the style guide are now in their own .rst files, I currently have the contents of these files just 'included' in the main style-guide.rst file, e.g.:

.. include:: git-and-github-workflow.rst
.. include:: python-coding.rst
.. include:: api-documentation.rst
.. include:: poetry-environment.rst
.. include:: security.rst
.. include:: naming-conventions.rst
.. include:: tools-and-library-recommendations.rst
.. include:: versioning.rst
.. include:: checklist-for-pull-requests.rst

Therefore, when viewing the docs on RTD, they still appear as subsections of the style guide instead of their own separate pages. I have been struggling to figure out how to create separate pages AND have the navigation bar look like:

Style Guide
  git and GitHub Workflow
  Python Coding
  Poetry Environment
  ...

@maxinelasp Do you know how I might accomplish getting these sections into their own pages, and also get the navigation to reflect that these pages are under the Style Guide 'umbrella'?

[maxinelasp]

Yes, you can use a toctree to do that. See index.rst for an example for how it looks in production. I think that will accomplish what you're looking for.

[maxinelasp]

I think .. include:: just embeds the document into the main one, which doesn't seem right. I'd recommend taking that out. I think it's also causing some errors in the build process about duplicate labels, although I'm not sure if that's some other issue instead.

[bourque]

Thanks @maxinelasp

I am still a little confused. If I use this in index.rst:

.. toctree::
    :maxdepth: 1

    doc-overview
    release-workflow
    style-guide
    git-and-github-workflow
    python-coding
    api-documentation
    poetry-environment
    security
    naming-conventions
    tools-and-library-recommendations
    versioning
    checklist-for-pull-requests

This does create separate pages for each of the items like I want. But it results in a navigation that looks like this:

It would be ideal if the style-guide page could act as a parent page/tree to the other sections, something like:

Contributing to Documentation
Release Workflow
Style Guide
|    git and GitHub workflow
|    Python Coding
|    ...etc

I tried messing with maxdepth but that just seems to control which subsections of a file get displayed. I also tried moving the sections of the style guide into their own style_guide subdirectory and trying things that way.

I must also be googling the wrong combination of words because I can't seem to find a relevant StackOverflow or equivalent 😬

[maxinelasp]

You can create a new folder ("development/style_guide") and add all documents under that. Then, create a toctree in style_guide.rst that has all the new files you want. Then, update index.rst to only have style_guide in the toctree. This creates another layer in the files:
index.rst > style_guide.rst > python_coding, git_workflow, etc

This way, the main index.rst will only link to the main style guide page, but the style guide page will then link to all the sub pages. Is that what you want?

[bourque]

Ahh, perfect, thank you @maxinelasp!

[bourque]

@maxinelasp Now could you review this? 😅

No need to review the content of the pages as those have not changed.

[maxinelasp]

Looks great and runs without errors! Thanks for doing this, I think it's a lot easier to navigate!