# Moving Developer and Scenario guides to a collection
###### tags: `Documentation`

Many developer and scenario guides in docs.ansible.com need to be moved from the ansible/ansible repository into the individual collection repository. Follow these sections to learn how.

## Steps to move the guides

You should check for a relevant scenario guide as well as for specific development guides that relate to your collection.

To move these guides:

1. Migrate to the files to your collection docs/docsite/rst folder.
2. Update anchors to use collection name and namespace to ensure they are unique. `ansible_collections.community.vmware.docsite.dev_guide` for example. NOTE: each rst file in a collection needs a unique anchor so make sure to add what the guide is as part of this anchor (dev_guide, scenario_guide, etc)
3. Test the docs locally as described in the next section.
4. Republish collection and verify the docs show up on [devel docs](https://docs.ansible.com/ansible/devel/collections/amazon/aws/index.html#plugins-in-amazon-aws) the next day.
5. Stub out the old guide in ansible/ansible repository with a :ref: link to the new anchor you produced in step 2. NOTE - if the guide isn't published yet, CI will produce failures until the guide is published.

See https://github.com/ansible/ansible/pull/77608 for an example of these steps.

## Testing Collection documentation locally

There is currently no easy way to verify guides within a collection will build properly.

Follow these steps:

1. Create a clean venv for this testing and `pip install ansible-core`.
2. Use `antsibull-docs sphinx-init --use-current namespace.collection_name` to generate the build.sh, conf.py, and requirements.txt and copy into your own docs/preview directory for your test collection.
3. (Optional) Edit `build.sh` to change any options or CLI arguments in the generated build script.
4. Install the requirements in your new venv: `pip install -r requirements.txt`.
5. (Optional) Add your rst files and `extra-docs.yml` as explained here.
6. Run the script to include the directory where your test collection lives as `ansible_collections/my/collection`: `ANSIBLE_COLLECTIONS=~/collections-sources/ ./build.sh`
7. Review the output and fix any problems.
8. View the rendered pages by opening the `html` directory and browsing the site. When the build is successful it's also important to check that things rendered the way you expected, that links point to the right place, etc.

See the GitHub actions for this; these can be used today to verify a clean docs build in collections: https://github.com/ansible-community/github-docs-build. The github-docs-build actions to do automated build/publish in a collection

# Adding Edit on Github to your collection

This feature is opt-in but we recommend that you include it in your collection.

To turn this feature on:

1. Add `docs/docsite/links.yml` to your collection.
2. Add edit on github link:

edit_on_github:
  repository: ansible-collections/mynamspace.mycollection
  branch: main
  path_prefix: ''

3. Consider adding other helpful links. See https://github.com/ansible-collections/community.general/blob/main/docs/docsite/links.yml#L1-L5 for an example.