Allow `great-docs.yml` and build dir to live inside `docs`

[cliffckerr]

TLDR -- I think many users would prefer to have an option for the all the docs content live inside docs rather than at the project root, especially for complex projects.

Currently, great-docs.yml and the build dir (great-docs/) are located at project root, and each docs subsection (e.g. user_guide, examples) is also expected to live at project root.

For Python projects, the root folder can get kind of crowded. For tidiness, I personally would prefer if everything was (or at least had an option to be be) kept inside docs, including great-docs.yml, the build folder, and the content source folders. This would match how both Quarto and Sphinx work, and almost matches MkDocs, with the exception that mkdocs.yml (unlike _quarto.yml and Sphinx's conf.py) lives at root.

To be specific, Great Docs' current structure (from here) is:

your-project/
├── great-docs.yml           # Configuration (committed to git)
├── great-docs/              # Build directory (gitignored, ephemeral)
│   ├── _quarto.yml          # Generated Quarto config
│   ├── index.qmd            # Landing page (from README.md)
│   ├── ...
│   └── _site/               # Built HTML site
│       ├── index.html
│       └── ...
├── user_guide/              # Your narrative docs (optional)
│   ├── 01-installation.qmd
│   └── ...
├── pyproject.toml
├── README.md
└── your_package/
    └── ...

The proposed alternative would be:

your-project/
├── docs/
│   ├── great-docs.yml           # Configuration (committed to git)
│   ├── _build/                  # Build dir -- **was ./great-docs, now ./docs/_build**
│   │   ├── _quarto.yml          # Generated Quarto config
│   │   ├── index.qmd            # Landing page (from README.md)
│   │   └── ...
│   └── _site/                   # Built site -- **was ./great-docs/_site, now ./docs/_site**
│   ├── index.html
│   └── ...
│   ├── examples/               # Custom folder -- **would have lived at root before**
│   │   ├── 01-hello-world.qmd
│   │   └── ...
│   ├── user_guide/              # Additional narrative docs (optional)
│   │   ├── 01-installation.qmd
│   │   └── ...
│   ├── README.md
│   └── .gitignore               # Ignore **was ./great-docs, now ./_build/ and ./_site/** 
├── pyproject.toml
├── your_package/
│   └── ...

A couple notes:

• Why move _site out of the build folder and at the same level as great-docs.yml? This is to parallel Python's build and dist folders, and because semantically the built site is distinct from the files that were used to build the site. However this part of the proposal is very much just a thought!
• Why rename great-docs to _build? In big projects using unfamiliar libraries, it can be a pain to distinguish source files from auto-generated ones. _build makes it clear it's an artifact rather than part of the source code. Otherwise, it might be confusing that great-docs.yml is tracked but great-docs/ is untracked. (Alternatives to _build could be .great-docs, a la .quarto, or just _great-docs.)

I'd definitely be happy to not use the same folder structure as used by Sphinx/MkDocs/Quarto, if an alternative makes more sense ... but I feel that for a lot of Python projects, it's one of the more elegant layouts.

[rich-iannone]

Thanks @cliffckerr for this suggestion, it's a good one. We will take this one on and follow the guidance here pretty closely (everything sounds quite reasonable!). The key thing will be ensuring that the current layout will continue to be supported well and that the new layout as proposed here will be essentially equivalent.

The new layout will be the preferred way to set up Great Docs and so the documentation will move to that and the legacy layout will be still in the documentation but diminished over time. This soft deprecation will also involve messaging in the build logs as well, pointing users to the new way and the relevant documentation.