Skip to content

DOCUMENTATION.md

Latest commit

 

History

History
84 lines (55 loc) · 2.83 KB

DOCUMENTATION.md

File metadata and controls

84 lines (55 loc) · 2.83 KB

Documentation

Tip: Use https://deepwiki.com/GITHUB-ORGANIZATION-NAME/REPOSITORY-NAME to have Artificial Intelligence automatically document the GitHub repository for you.

Read the Docs: GITHUB-ORGANIZATION-REPOSITORY-NAME

100 - Install ReadTheDocs

Run the following command:

$ pip install sphinx sphinx_rtd_theme recommonmark

Next to create the docs run:

$ cd docs
$ make html

Your docs will be created inside docs/build.

200 - Autogeneration of ReadTheDocs

  1. Make sure there is a .readthedocs.yml file at the root of your GitHub repository.

  2. Connect your GitHub repository to ReadTheDocs at https://readthedocs.org/

  1. Go to ReadTheDocs and create an account
  2. Click "Import a Project"
  3. Connect your GitHub account if you haven't already
  4. Select your repository from the list
  5. Configure your project settings

300 - Build Your Documentation

  1. Push your changes to GitHub
  2. ReadTheDocs will automatically build your documentation
  3. Visit your project page on ReadTheDocs to see the result

400 - Set Up Webhooks (Optional)

ReadTheDocs should automatically set up webhooks, but if not:

  1. Go to your repository settings on GitHub
  2. Go to Webhooks
  3. Add a webhook with the URL from your ReadTheDocs project settings

500 - Troubleshooting

  • Build fails: Check the build logs on ReadTheDocs
  • Missing content: Ensure all files are included in your toctree
  • Formatting issues: Check that your Markdown/reStructuredText is valid
  • Images not showing: Verify paths to images are correct

600 - Maintaining Your Documentation

  • Update your documentation files as needed
  • Push changes to GitHub
  • ReadTheDocs will automatically rebuild
  • Use ReadTheDocs' versioning feature to maintain documentation for different releases

700 - Trigger a build on ReadTheDocs

On ReadTheDocs, after logging in navigate to your GitHub repository entry (e.g., https://app.readthedocs.org/projects/YOUR-GITHUB-REPOSITOY-NAME/) and from the dotted menu (...) choose Rebuild version.

800 - Tips

  • Images: Move images to docs/source/_static/ and update references
  • Code blocks: Ensure proper syntax highlighting is specified
  • Cross-references: Update to use Sphinx's reference system
  • Metadata: Add appropriate metadata to each page for better SEO

900 - Common Issues

  • Broken links: Double-check all links after conversion
  • Missing images: Ensure all image paths are updated
  • Build failures: Check the ReadTheDocs build logs for errors
  • Formatting differences: Some Markdown features might render differently in Sphinx

1000 - View the Documentation

Visit https://GITHUB-ORGANIZATION-REPOSITORY-NAME.readthedocs.io/en/latest/