From 8c7ce8873dec0bb94246abcffa3ca221377b613e Mon Sep 17 00:00:00 2001 From: Casey Wilson Date: Fri, 9 Feb 2024 11:33:26 -0500 Subject: [PATCH] fix: update make targets and docs (#41) --------- Co-authored-by: Adriel Perkins --- Makefile | 6 +++--- README.md | 44 +++++++++++++++++++++++++++++++++----------- 2 files changed, 36 insertions(+), 14 deletions(-) diff --git a/Makefile b/Makefile index 83ad568..eba0d2e 100644 --- a/Makefile +++ b/Makefile @@ -10,11 +10,11 @@ build: poetry-install poetry run mkdocs build .PHONY: serve -serve: +serve: poetry-install poetry run mkdocs serve -.PHONY: install-deps -install-deps: +.PHONY: brew +brew: brew bundle --force .PHONY: backstage diff --git a/README.md b/README.md index 54248b9..99e7bb9 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,47 @@ # openo11y.dev -Welcome to Open O11y! This repository hosts the website files for [openo11y.dev](https://openo11y.dev), an open-source public website with guidance and information on observability (o11y). +Welcome to OpenO11y! This repository hosts the website files for +[openo11y.dev](https://openo11y.dev), an open-source public website dedicated +to providing guidance and resources on observability (o11y). -If you're looking to contribute, please see the [contributing](./docs/contributing.md) documentation. +If you're looking to contribute, please see the +[contributing](./docs/contributing.md) documentation. ## Local Development -### MkDocs +### Prerequisites -The site is built using `mkdocs`. You can serve the site locally by running +The following tools will need to be installed: -```sh -make install-deps -make build -make serve -``` +- [Make](https://www.gnu.org/software/make/): A build automation tool. +- [Python](https://www.python.org/downloads/): The programming language used + for development. +- [Poetry](https://python-poetry.org/docs/#installation): A tool for dependency + management in Python. + +Note: OSX users with [Homebrew](https://brew.sh/) installed can install Poetry +by running the command `make brew`. + +### Working on Documentation + +Our site is built using [mkdocs](https://www.mkdocs.org/), a static site +generator optimized for project documentation. It features hot reloading, +allowing immediate preview of changes, and can compile documentation into +static assets for deployment. + +To work on the documentation: + +- Use `make serve` to start a local server. Your changes can be viewed in + real-time at http://127.0.0.1:8000. +- To build the documentation, run `make build`. This command generates static + files and stores them in the `./site` directory. ## Contributing - Follow the guidelines established in [CONTRIBUTING.md](docs/CONTRIBUTING.md) -- Images should be placed under the root `img` folder and referred to using HTML `` tags +- Images should be placed under the root `img` folder and referred to using + HTML `` tags - H3 header (`###`) should be the default header within a page -- H2 header (`##`) will appear in the navigation as the page's table of contents +- H2 header (`##`) will appear in the navigation as the page's table of + contents - make sure to add to _sidebar