|
| 1 | +[MyST]: https://mystmd.org |
| 2 | +[MyST Markdown]: https://mystmd.org/guide/quickstart |
| 3 | +[Table of Contents]: https://mystmd.org/guide/table-of-contents |
| 4 | + |
| 5 | + |
1 | 6 | # Quickstart |
2 | 7 |
|
3 | | -## Installation |
| 8 | +## Installation and Initialization |
4 | 9 |
|
5 | 10 | ```bash |
6 | 11 | # install afterpython as a dev dependency |
7 | 12 | uv add --dev afterpython |
8 | | -# initialize afterpython |
| 13 | + |
| 14 | +# initialize afterpython/ |
9 | 15 | ap init |
10 | 16 | ``` |
11 | 17 |
|
12 | | -## afterpython/ Directory |
13 | | -after initialization, a folder afterpython/ is created |
| 18 | +--- |
| 19 | +## Writing Content |
| 20 | +After running `ap init`, the `afterpython/` directory is created and you can start writing content right away. |
| 21 | + |
| 22 | +The structure of `afterpython/` is as follows: |
| 23 | +- `afterpython/doc/` |
| 24 | +- `afterpython/blog/` |
| 25 | +- `afterpython/tutorial/` |
| 26 | +- `afterpython/example/` |
| 27 | +- `afterpython/guide/` |
| 28 | + |
| 29 | +All these subdirectories are initialized by `myst init` (see [MyST Markdown]), with a default `index.md` file for each content type. |
| 30 | + |
| 31 | +For example, to start writing documentation of your project, run `ap doc` to start the development server for the `afterpython/doc/` directory, then create a new `.md` or `.ipynb` file in `afterpython/doc/`. |
| 32 | + |
| 33 | +You can then view the documentation at `http://localhost:3000/` (or the port specified by `ap doc --port`). |
| 34 | + |
| 35 | +Similarly, you can start the development server for other content types by running `ap blog`, `ap tutorial`, `ap example`, or `ap guide`, and then create `.md` or `.ipynb` files in the corresponding directory. |
| 36 | + |
| 37 | +:::{seealso} |
| 38 | +To learn more about how to arrange your content, see [Table of Contents] or a [Quick Guide about myst.yml](walkthrough/myst_yml.md). |
| 39 | +::: |
| 40 | + |
| 41 | +--- |
| 42 | +## Project Website |
| 43 | +A project website is basically a website that serves as the **homepage for your project**. |
14 | 44 |
|
| 45 | +It sits on top of your content, including documentation, blog posts, tutorials, examples, and guides. |
15 | 46 |
|
16 | | -## afterpython.toml |
| 47 | +You can run `ap dev` to start the development server for the project website to see how everything looks and works together. |
17 | 48 |
|
| 49 | +Note that this server is **independent** from the development servers for your content — you need to run `ap doc` to start another server for the *Documentation tab* in your website to work. |
18 | 50 |
|
19 | | -## static/ Directory |
| 51 | +For convenience, you can run `ap dev --all` to start the development server for all content types and the project website at once, so that you don't need to run `ap doc`, `ap blog`, `ap tutorial`, `ap example`, or `ap guide` separately. |
| 52 | + |
| 53 | +:::{tip} Standard Workflow |
| 54 | +The typical workflow is: |
| 55 | +- Run `ap doc` (and other content types) and start writing content |
| 56 | +- When finished, run `ap dev --all` to see what the final project website looks like |
| 57 | +::: |
| 58 | + |
| 59 | +See [](project_website.md) for more details. |
| 60 | + |
| 61 | +--- |
| 62 | +## Build & Preview |
| 63 | +To build for production, run `ap build`. |
| 64 | + |
| 65 | +run `ap preview` to preview the production build of the project website. |
| 66 | + |
| 67 | + |
| 68 | +--- |
| 69 | +## Deploy |
| 70 | +A `deploy.yml` file is created in the `.github/workflows/` directory during initialization, which is a GitHub Actions workflow for deploying the project website to GitHub Pages. |
| 71 | + |
| 72 | +By default, it will be triggered for deployment when you push any content changes to the `main` branch. If you don't want this, you can: |
| 73 | +- write content in a different branch, or |
| 74 | +- disable the workflow by commenting out the `on: push` section in the `deploy.yml` file |
20 | 75 |
|
21 | 76 |
|
22 | 77 | :::{important} `afterpython` badge |
23 | | -If you like `afterpython`, consider add this badge [](https://afterpython.org) to your python project's `README.md` by: |
| 78 | +To support `afterpython`, consider adding this badge [](https://afterpython.org) to your python project's `README.md` by writing: |
| 79 | + |
24 | 80 | `[](https://afterpython.org)` |
25 | 81 | ::: |
| 82 | + |
| 83 | +:::{seealso} Quick Guide to MyST |
| 84 | +:class: dropdown |
| 85 | +[MyST] is the document engine that powers `afterpython`. You may want to read the [Quick Guide to MyST](myst.md) to understand what you can do with it before writing content. |
| 86 | +::: |
0 commit comments