Skip to content

Update README #600

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
a-velasco wants to merge 1 commit into from
Closed

Update README #600

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 44 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,39 +1,64 @@
# Canonical's Sphinx Starter Pack

*A pre-configured repository to build and publish documentation with Sphinx.*
[![Test starter pack](https://github.com/canonical/sphinx-docs-starter-pack/actions/workflows/test-starter-pack.yml/badge.svg)](https://github.com/canonical/sphinx-docs-starter-pack/actions/workflows/test-starter-pack.yml)

## Description
A pre-configured repository to build documentation with [Sphinx] and publish it on [Read The Docs].

The Documentation starter pack includes:
The Starter Pack contains build instructions, extensions with styling and configuration options, and automatic documentation checks.

* A bundled [Sphinx] theme, configuration, and extensions
* Support for both reStructuredText (reST) and MyST Markdown
* Build checks for links, spelling, and inclusive language
* Customisation support layered over a core configuration
## Using the Starter Pack

See the full documentation: https://canonical-starter-pack.readthedocs-hosted.com/
This repository contains example documentation that can be built out of the box.

## Structure
To try it out, clone it locally and navigate to the `/docs` folder:

This section outlines the structure of this repository, and some key files.
```shell
git clone git@github.com:canonical/sphinx-docs-starter-pack.git
cd docs
```

### `docs/`
Then, run the command

This directory contains the documentation for the starter pack itself.
```shell
make run
```

To view it in your browser, navigate to this directory and type `make run`.
This will create a Python virtual environment, install necessary dependencies, build the documentation, and serve it in a local webserver.

### `.github/workflows/`
You can access it in your browser at http://127.0.0.1:8000.

This directory contains files used for documentation build checks via GitHub's CI.
To learn more about how to install and configure the Starter Pack for your own project, see the [Set up a new project](https://canonical-starter-pack.readthedocs-hosted.com/stable/tutorial/set-up/) guide in the official documentation.

The file `test-starter-pack.yml` tests the functionality of the starter pack project.
## Requirements and limitations

## Contributing
<!--Local build requirements - any linux OS? python preinstalled? I feel like this should be clarified in the section above though-->

We welcome contributions to this project! If you have suggestions, bug fixes, or improvements, please open an issue or submit a pull request.
The Starter Pack is designed for projects hosted on GitHub. This is necessary to run the automatic checks in .github/workflows, and to publish your documentation on Read The Docs.

Please read and sign our [Contributor Licence Agreement (CLA)] before submitting any changes. The agreement grants Canonical permission to use your contributions. The author of a change remains the copyright owner of their code (no copyright assignment occurs).
If you have a project that is hosted on a different versioning platform, like Launchpad, [reach out to us](#reach-out).

## Community and support

The Canonical Sphinx Starter pack is an open-source project that warmly welcomes community involvement.

If you’re new to the community, make sure to read through the [Ubuntu Code of Conduct](https://ubuntu.com/community/code-of-conduct) first.

### Reach out

* Report an issue or make a suggestion via [GitHub](https://github.com/canonical/sphinx-docs-starter-pack/issues)
* Come chat with the Canonical Documentation team in our [public Matrix channel](https://matrix.to/#/#documentation:ubuntu.com)

### Contribute

The Starter Pack provides a shared foundation for Sphinx documentation projects, and contributions help improve the documentation of all its users.

* See [CONTRIBUTING.md](CONTRIBUTING.md) for more details about contributing to development or documentation
* Check [open issues](https://github.com/canonical/sphinx-docs-starter-pack/issues)

<!--
Tempted to remove this, since it's clearly explained in CONTRIBUTING.md

Please read and sign our [Contributor Licence Agreement (CLA)] before submitting any changes. The agreement grants Canonical permission to use your contributions. The author of a change remains the copyright owner of their code (no copyright assignment occurs).-->

<!--Links-->

Expand Down
Loading