Mercurial > piecrust2

annotate docs/pages/support.md @ 1188:a7c43131d871

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
bake: Fix file write flushing problem with Python 3.8+ Writing the cache files fails in Python 3.8 because it looks like flushing behaviour has changed. We need to explicitly flush. And even then, in very rare occurrences, it looks like it can still run into racing conditions, so we do a very hacky and ugly "retry" loop when fetching cached data :(
author Ludovic Chabant <ludovic@chabant.com>
date Tue, 15 Jun 2021 22:36:23 -0700
parents c53af44457b6
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
243
26e59f837558 docs: Add embryo of a documentation website.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
1 ---
26e59f837558 docs: Add embryo of a documentation website.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
2 title: Support
1053
94d7d5e38571 docs: Upgrade to Bootstrap 4 and Sass.
Ludovic Chabant <ludovic@chabant.com>
parents: 741
diff changeset
3 header_class: pc-support
94d7d5e38571 docs: Upgrade to Bootstrap 4 and Sass.
Ludovic Chabant <ludovic@chabant.com>
parents: 741
diff changeset
4 nav_key: support
243
26e59f837558 docs: Add embryo of a documentation website.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
5 ---
26e59f837558 docs: Add embryo of a documentation website.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
6
1077
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
7 ## Changelog
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
8
741
0c3b811d2c26 docs: Add changelog page.
Ludovic Chabant <ludovic@chabant.com>
parents: 325
diff changeset
9 Want to know what's new with PieCrust? Check out the [CHANGELOG][ch].
0c3b811d2c26 docs: Add changelog page.
Ludovic Chabant <ludovic@chabant.com>
parents: 325
diff changeset
10
1077
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
11
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
12 ## General Support
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
13
325
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
14 If you have a problem with PieCrust, there are a few ways to solve it:
243
26e59f837558 docs: Add embryo of a documentation website.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
15
325
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
16 * Check the [documentation][doc] one more time! You never know, the solution may be in
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
17 there.
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
18 * Is the documentation wrong or missing something? If you know what must be
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
19 fixed, you can get the source from [BitBucket][bbsrc] or [Github][ghsrc] and
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
20 make a pull request.
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
21 * If you're pretty sure you found a bug, please file a report on
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
22 [BitBucket][bbbug] or [Github][ghbug]. If by chance you've already fixed it,
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
23 even better! Make a pull request, you know the drill.
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
24 * If you have questions, hit the [me][] on [Twitter][].
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
25
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
26
1077
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
27 ## Upgrading PieCrust
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
28
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
29 ### Version 2 to 3
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
30
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
31 Several things have changed between version 2 and 3, and some of them introduce
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
32 breaking changes.
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
33
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
34 #### Generated page templates
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
35
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
36 Previously, taxonomy listing pages had their template defined as a page with
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
37 a special name. For instance, tag lists were by default defined by
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
38 `pages/_tag.html`.
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
39
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
40 Now those page templates are proper templates, found in the `templates`
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
41 directory (or other if you changed that). The tag list is now
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
42 `templates/_tag.html` for instance.
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
43
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
44 In general, you should only have to move your template for the `pages` folder to
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
45 the `templates` folder.
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
46
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
47 #### Generators
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
48
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
49 There is no more `generators` in the website configuration -- everything is
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
50 a content source. If you had custom generators in their, you will need to
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
51 re-declare them as standard sources.
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
52
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
53 For example, a new taxonomy source would be defined like this:
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
54
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
55 ```
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
56 site:
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
57 sources:
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
58 post_tags:
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
59 type: taxonomy
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
60 taxonomy: tags
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
61 source: posts
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
62 ```
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
63
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
64 In this example, `tags` is a taxonomy declared the same way as previously inside
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
65 `site/taxonomies`, and `posts` is a normal page source declared also in the same
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
66 way as previously.
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
67
c53af44457b6 docs: Add some information about migrating from v2 to v3.
Ludovic Chabant <ludovic@chabant.com>
parents: 1053
diff changeset
68
325
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
69 [doc]: {{docurl('')}}
741
0c3b811d2c26 docs: Add changelog page.
Ludovic Chabant <ludovic@chabant.com>
parents: 325
diff changeset
70 [ch]: {{pcurl('support/changelog')}}
325
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
71 [bbsrc]: https://bitbucket.org/ludovicchabant/piecrust2
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
72 [bbbug]: https://bitbucket.org/ludovicchabant/piecrust2/issues?status=new&status=open
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
73 [ghsrc]: https://github.com/ludovicchabant/PieCrust2
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
74 [ghbug]: https://github.com/ludovicchabant/PieCrust2/issues
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
75 [me]: http://ludovic.chabant.com
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
76 [twitter]: https://www.twitter.com/ludovicchabant
c750dc21d55d docs: Quick support info page.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
77