Docs Publisher issueshttps://lab.civicrm.org/documentation/docs-publisher/-/issues2019-05-21T09:59:45Zhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/67Delete NotifyControllerTest.php2019-05-21T09:59:45ZSean ColsenDelete NotifyControllerTest.php@michaelmcandrew you seem to have created [this file](https://lab.civicrm.org/documentation/docs-publisher/blob/9a8d18b585f2731a8c12cb26a9dc2dbc3f9c4172/src/AppBundle/Tests/Controller/NotifyControllerTest.php) but as far as I can tell it...@michaelmcandrew you seem to have created [this file](https://lab.civicrm.org/documentation/docs-publisher/blob/9a8d18b585f2731a8c12cb26a9dc2dbc3f9c4172/src/AppBundle/Tests/Controller/NotifyControllerTest.php) but as far as I can tell it doesn't do anything.
Can we either:
1. delete it (my preference, since there's really not much there)
1. *or* move it to the `/tests` folder at the root level and add enough code to the file to make it useful.
I'm just trying to do a little housekeeping and this file seemed unnecessary. Perhaps I'm wrong though!https://lab.civicrm.org/documentation/docs-publisher/-/issues/88Live "What is CiviCRM?" doesn't list Backdrop, but Github does list Backdrop2019-05-16T16:18:09ZCM ToolanLive "What is CiviCRM?" doesn't list Backdrop, but Github does list BackdropNot 100% sure if this is the right place, but there seems to be an odd difference between what's live on the docs site and the GitHub repository. GitHub lists all four possible CMS choices, but the live site is missing Backdrop.
https:/...Not 100% sure if this is the right place, but there seems to be an odd difference between what's live on the docs site and the GitHub repository. GitHub lists all four possible CMS choices, but the live site is missing Backdrop.
https://docs.civicrm.org/user/en/latest/introduction/what-is-civicrm/
Live:
![Screen_Shot_2019-05-09_at_21.49.33](/uploads/02b3a138d9f224b4407fe230477b5303/Screen_Shot_2019-05-09_at_21.49.33.png)
GitHub:
https://github.com/civicrm/civicrm-user-guide/blob/master/docs/introduction/what-is-civicrm.md
![Screen_Shot_2019-05-09_at_21.49.58](/uploads/99a6871699da692db44d0ff110639834/Screen_Shot_2019-05-09_at_21.49.58.png)https://lab.civicrm.org/documentation/docs-publisher/-/issues/14Automatic publishing of extension-specific books, when possible2018-11-08T04:23:30ZSean ColsenAutomatic publishing of extension-specific books, when possible*Created by: seanmadsen*
should doc infra interact with extension `info.xml` files?
migrated from [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f688#to-do).*Created by: seanmadsen*
should doc infra interact with extension `info.xml` files?
migrated from [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f688#to-do).https://lab.civicrm.org/documentation/docs-publisher/-/issues/15Custom theme2018-11-08T04:23:30ZSean ColsenCustom theme*Created by: seanmadsen*
A CiviCRM theme for documentation with the following goals:
* display the version branch version (e.g. in user guide, show "4.6" or "latest")
* link to docs.civicrm.org documentation home page (to allow us...*Created by: seanmadsen*
A CiviCRM theme for documentation with the following goals:
* display the version branch version (e.g. in user guide, show "4.6" or "latest")
* link to docs.civicrm.org documentation home page (to allow user to switch between books/versions/etc)
* link to civicrm.org home page
* colors/branding matching CiviCRM branding, to some degree (not aiming for 100% match here, but at least a little bit)
* more control over future theme-level features as needed
migrated from [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f688#to-do).https://lab.civicrm.org/documentation/docs-publisher/-/issues/17Create "Administrator Guide" book, separate from User Guide and Developer Guide2018-11-08T04:23:30ZSean ColsenCreate "Administrator Guide" book, separate from User Guide and Developer Guide*Created by: seanmadsen*
We currently have a User Guide and a Developer Guide. The addition of an Administrator Guide would round out the documentation and cover topics such as installing/updating core, finding/installing extensions, ...*Created by: seanmadsen*
We currently have a User Guide and a Developer Guide. The addition of an Administrator Guide would round out the documentation and cover topics such as installing/updating core, finding/installing extensions, and basic troubleshooting. Some of this content is currently in the User Guide (e.g. [here](https://docs.civicrm.org/user/en/stable/initial-set-up/installation-and-basic-set-up/)) and some of it is in the wiki (e.g. [here](https://wiki.civicrm.org/confluence/display/CRMDOC/Installation+and+Upgrades)).
migrated from [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f688#to-do).https://lab.civicrm.org/documentation/docs-publisher/-/issues/18Home page which gives list of all books in system2018-11-08T04:23:30ZSean ColsenHome page which gives list of all books in system*Created by: seanmadsen*
The docs system should provide a welcoming home page at docs.civicrm.org which lists all the books defined in `app/config/books/`.
migrated from [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e...*Created by: seanmadsen*
The docs system should provide a welcoming home page at docs.civicrm.org which lists all the books defined in `app/config/books/`.
migrated from [to-do list](https://github.com/civicrm/civicrm-docs/tree/638e243c6f4eb06086199e3ea8b529541368f688#to-do).https://lab.civicrm.org/documentation/docs-publisher/-/issues/20System to create internal redirects within each book2018-11-08T04:23:30ZSean ColsenSystem to create internal redirects within each book*Created by: seanmadsen*
Within the Developer Guide content migration, a [need](https://github.com/civicrm/civicrm-dev-docs/issues/25) emerged rather quickly to be able to move a page without giving a 404 error to any incoming links. Th...*Created by: seanmadsen*
Within the Developer Guide content migration, a [need](https://github.com/civicrm/civicrm-dev-docs/issues/25) emerged rather quickly to be able to move a page without giving a 404 error to any incoming links. The docs system should provide a way for each book to specify internal redirects.
MkDocs has [stated](https://github.com/mkdocs/mkdocs/issues/45#issuecomment-234826923) that they want redirection to happen at the server level, so it seems our docs system should be responsible for providing this feature.
For comparison, Read The Docs [offers](http://read-the-docs.readthedocs.io/en/latest/user-defined-redirects.html#page-redirects) this feature. Though, as someone who has never used RTD, reading their description of this feature still leaves me somewhat confused as to the process that content editors must follow to create such redirects. https://lab.civicrm.org/documentation/docs-publisher/-/issues/21Change docs system to work with Apache instead of nginx2018-11-08T04:23:30ZSean ColsenChange docs system to work with Apache instead of nginx*Created by: seanmadsen*
@michaelmcandrew and I talked on Mattermost yesterday about the steps needed to implement [internal redirects](https://github.com/civicrm/civicrm-docs/issues/20) for each book, which is a high-priority issue, sl...*Created by: seanmadsen*
@michaelmcandrew and I talked on Mattermost yesterday about the steps needed to implement [internal redirects](https://github.com/civicrm/civicrm-docs/issues/20) for each book, which is a high-priority issue, slowing the progress of content migration within the Developer Guide. Michael recommended that switching the server from nginx to Apache would make this internal redirects project easier. This issues requires changes within the docs app so that it runs reliably on Apache, including reading and [manual publishing via URL](https://github.com/civicrm/civicrm-docs#manual-publishing). https://lab.civicrm.org/documentation/docs-publisher/-/issues/39book publishing should fail more gracefully when page-building errors are enc...2018-11-08T04:23:30ZSean Colsenbook publishing should fail more gracefully when page-building errors are encountered*Created by: seanmadsen*
On 2017-02-04 we had a little snafu with the Dev Guide. Here's what happened, chronologically:
1. On 2017-02-03 Michael (at my request) took [these steps](https://github.com/squidfunk/mkdocs-material/issues/...*Created by: seanmadsen*
On 2017-02-04 we had a little snafu with the Dev Guide. Here's what happened, chronologically:
1. On 2017-02-03 Michael (at my request) took [these steps](https://github.com/squidfunk/mkdocs-material/issues/138#issuecomment-276567696) to install a more bleeding edge version of `pymdown-extensions` in attempt at addressing [civicrm-docs-material#7](https://github.com/civicrm/civicrm-docs-material/issues/7)
1. Shortly thereafter, I made [3 commits](https://github.com/civicrm/civicrm-dev-docs/commits/hooks-op-4), tested them locally with success (with the same version of `pymdown-extensions`), and then pushed them to the `hooks-op-4` branch of `civicrm-dev-docs`.
1. After this push, the docs system attempted to publish the `hooks-op-4` branch but encountered an error that I am fairly certain stemmed from a bug within `pymdown-extensions` and caused by the more bleeding edge version. Unfortunately I have not been able to reproduce this bug locally :slightly_frowning_face:
* The full error output is below
* Most notably: `ERROR - Error building page markdownrules.md`
1. Unfortunately MkDocs didn't handle this error gracefully because it built all the pages up to `markdownrules.md` (as listed in `mkdocs.yml`) and then stopped there without attempting to build any pages listed *after* `markdownrules.md`. (That's too bad, but seems like an upstream issue with MkDocs that we probably can't control so easily.)
* **(Issue A)**: What *would* be good, is if civicrm-docs could *attempt* to build a book, and then only make it live if the build process completes succesfully.
1. The especially bad (and strange) thing that happened here is that *somehow* the `latest` and `master` versions of the Dev Guide also ended up pointing to this botched branch of `hooks-op-4`.
* **(Issue B)**: The errors in publishing one branch ended up messing up another branch. I imagine we should be able to prevent this somehow.
1. Then on 2017-02-04 @ErichBSchulz [pointed out](https://chat.civicrm.org/civicrm/pl/rk56wfjx9bfqbj69hfw6fyfj3c) the problem with the master branch, and I tried to re-publish that branch (without publishing `hooks-op-4`) by loading `https://docs.civicrm.org/admin/publish/dev/en/master`
* **(Issue C)**: publishing the master branch with the URL above didn't work during this time when the Dev Guide was "messed up". I forget the exact error I got when I tried. Either 404 or 500 or 503.
1. Then I asked @bgm to do the following on the server, and these steps got the `master` branch up and running again:
```bash
cd /path/to/civicrm-docs/site
./bin/console docs:publish dev/en/master
```
Again a can't reproduce any of this locally, so I'm not sure how best to proceed here. Hoping that @michaelmcandrew will think of something.
## Full error given by the publishing system
(This was emailed to me)
```text
Running 'mkdocs build -c -f /var/www/civicrm-docs/var/repos/buildfiles/dev.en.master.yml -d /var/www/civicrm-docs/app/../web/static/dev/en/master'
INFO: mkdocs output: '
INFO - Cleaning site directory
INFO - Building documentation to directory: /var/www/civicrm-docs/web/static/dev/en/master
ERROR - Error building page markdownrules.md Traceback (most recent call last):
File "/usr/local/bin/mkdocs", line 11, in sys.exit(cli())
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 722, in __call__ return self.main(*args, **kwargs)
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 697, in main rv = self.invoke(ctx)
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 1066, in invoke return _process_result(sub_ctx.command.invoke(sub_ctx))
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 895, in invoke return ctx.invoke(self.callback, **ctx.params)
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 535, in invoke return callback(*args, **kwargs)
File "/usr/local/lib/python2.7/dist-packages/mkdocs/__main__.py", line 156, in build_command ), dirty=not clean)
File "/usr/local/lib/python2.7/dist-packages/mkdocs/commands/build.py", line 379, in build build_pages(config, dirty=dirty)
File "/usr/local/lib/python2.7/dist-packages/mkdocs/commands/build.py", line 332, in build_pages dump_json)
File "/usr/local/lib/python2.7/dist-packages/mkdocs/commands/build.py", line 188, in _build_page site_navigation=site_navigation
File "/usr/local/lib/python2.7/dist-packages/mkdocs/commands/build.py", line 59, in convert_markdown extension_configs=config['mdx_configs']
File "/usr/local/lib/python2.7/dist-packages/mkdocs/utils/__init__.py", line 366, in convert_markdown html_content = md.convert(markdown_source)
File "/usr/local/lib/python2.7/dist-packages/markdown/__init__.py", line 368, in convert self.lines = prep.run(self.lines)
File "/usr/local/lib/python2.7/dist-packages/pymdown_extensions-1.8-py2.7.egg/pymdownx/superfences.py", line 484, in run lines = self.search_nested(lines)
File "/usr/local/lib/python2.7/dist-packages/pymdown_extensions-1.8-py2.7.egg/pymdownx/superfences.py", line 385, in search_nested self.eval(m, start, end)
File "/usr/local/lib/python2.7/dist-packages/pymdown_extensions-1.8-py2.7.egg/pymdownx/superfences.py", line 281, in eval self.process_nested_block(m, start, end)
File "/usr/local/lib/python2.7/dist-packages/pymdown_extensions-1.8-py2.7.egg/pymdownx/superfences.py", line 320, in process_nested_block code = entry["formatter"](self.rebuild_block(self.code), self.lang)
File "/usr/local/lib/python2.7/dist-packages/pymdown_extensions-1.8-py2.7.egg/pymdownx/superfences.py", line 423, in highlight lexer = guess_lexer(self.src) AttributeError: 'SuperFencesBlockPreprocessor' object has no attribute 'src'
```https://lab.civicrm.org/documentation/docs-publisher/-/issues/85Peg pip packages to specific versions in the Dockerfile2018-02-26T01:04:29ZSean ColsenPeg pip packages to specific versions in the DockerfileThe Dockerfile within this project installs some packages with pip. We should specify versions for those packages, and those versions should agree with what's installed on the live server.
Related: #84The Dockerfile within this project installs some packages with pip. We should specify versions for those packages, and those versions should agree with what's installed on the live server.
Related: #84https://lab.civicrm.org/documentation/docs-publisher/-/issues/84Upgrade to MkDocs 0.172018-02-26T01:03:17ZSean ColsenUpgrade to MkDocs 0.17On the live server, we are currently running MkDocs 0.16.1.
As of Oct, 2017, [MkDocs 0.17](http://www.mkdocs.org/about/release-notes/#version-0170-2017-10-19) is out. Unfortunately, it has some breaking changes with 0.16. The only motiv...On the live server, we are currently running MkDocs 0.16.1.
As of Oct, 2017, [MkDocs 0.17](http://www.mkdocs.org/about/release-notes/#version-0170-2017-10-19) is out. Unfortunately, it has some breaking changes with 0.16. The only motivation to upgrade (as far as I can tell) is just to keep up with things so that we don't fall too far behind. Currently, trying to publish a book with docs-publisher on a system that has MkDocs 0.17.0+ results in the following error:
> Build errors encountered. Book not published. Build error: 'MkDocs was unable to build the book. MkDocs command output: WARNING - Config value: 'theme_dir'. Warning: The configuration option {0} has been deprecated and will be removed in a future release of MkDocs.
WARNING - Config value: 'site_favicon'. Warning: Unrecognised configuration name: site_favicon Aborted with 2 Configuration Warnings in 'strict' mode!
I havnen't gotten too deep into this yet. Just deep enough to predict that it's going to be a bit of a project.https://lab.civicrm.org/documentation/docs-publisher/-/issues/83Infinite redirect loop2017-11-02T16:57:19ZSean ColsenInfinite redirect loopNot sure why this is happening. If you try going to https://docs.civicrm.org/user/en/4.6/current/email/scheduled-reminders you'll get a redirect error. (Note the incorrect URL with `4.6/current`.)
Looks like the page is redirecting to i...Not sure why this is happening. If you try going to https://docs.civicrm.org/user/en/4.6/current/email/scheduled-reminders you'll get a redirect error. (Note the incorrect URL with `4.6/current`.)
Looks like the page is redirecting to itself.
```
$ wget 'https://docs.civicrm.org/user/en/4.6/current/email/scheduled-reminders' 2>&1 | grep Location:
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
Location: /user/en/4.6/current/email/scheduled-reminders [following]
```
We should try to change the redirection logic so that a request like this gives a 404 response instead of a 301.
Reported by @wmortada [in Mattermost](https://chat.civicrm.org/civicrm/pl/ehiameh3oin8881s14ciwshsaa)https://lab.civicrm.org/documentation/docs-publisher/-/issues/81Only publish a guide if the docs within its repo have been changed2017-10-19T15:15:20ZSean ColsenOnly publish a guide if the docs within its repo have been changedIf an extension makes a code change (non-docs), the publisher will still re-publish the guide. When acting on webhook requests, we should look at either the webhook details or the git details to see if any docs files were changed and onl...If an extension makes a code change (non-docs), the publisher will still re-publish the guide. When acting on webhook requests, we should look at either the webhook details or the git details to see if any docs files were changed and only publish if they were.
CC @Michael_McAndrewhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/80Editing non-master branches with the pencil icon doesn't work2017-10-19T15:10:25ZSean ColsenEditing non-master branches with the pencil icon doesn't workSteps to reproduce:
1. Go to the home page of the User Guide 4.6 edition
https://docs.civicrm.org/user/en/4.6/
1. Hover over the pencil icon at the top right of the page
1. Expect the URL to be
https://github.com/civicrm/civic...Steps to reproduce:
1. Go to the home page of the User Guide 4.6 edition
https://docs.civicrm.org/user/en/4.6/
1. Hover over the pencil icon at the top right of the page
1. Expect the URL to be
https://github.com/civicrm/civicrm-user-guide/edit/4.6/docs/index.md
1. Observe the URL to be
https://github.com/civicrm/civicrm-user-guide/edit/master/docs/index.mdhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/51User Guide - label 4.7 as "Latest" and 4.6 as "LTS"2017-10-19T15:00:17ZSean ColsenUser Guide - label 4.7 as "Latest" and 4.6 as "LTS"*Created by: seanmadsen*
This is in response to a request from @nganivet [here](https://github.com/civicrm/civicrm-docs/pull/49#issuecomment-286637921). Specific changes to implement:
* [x] Update [civicrm.org/documentation](https://ci...*Created by: seanmadsen*
This is in response to a request from @nganivet [here](https://github.com/civicrm/civicrm-docs/pull/49#issuecomment-286637921). Specific changes to implement:
* [x] Update [civicrm.org/documentation](https://civicrm.org/documentation) to change the URL for User Guide 4.7 from `/user/en/stable` to `/user/en/latest` **(Done by Sean on 2017-03-15)**
* [x] Redirect `user/en/stable` to `/user/en/latest` **(Blocked by #50)** *(Note: this change is just to avoid giving 404s to any "stable" URLs which still exist in the wild, since people have been using this URL for the 4.7 version of the User Guide for quite some time now. The term "stable" would not be displayed to any readers anywhere, but would just function as a redirect)*
* [x] Redirect `/user/en/lts` to `/user/en/4.6` **(Blocked by #50)**
* [x] When describing the available editions of the User Guide to readers, do it as follows: **(Blocked by #50 and #48 and #46 )** *(Note: these descriptors will eventually be used in the auto-generated book home pages, as well as at the top of every page within the book when the book is built with the Material theme customizations)*
* "English – 4.7 (Latest)"
* "English – 4.6 (LTS)"
* "françias (French) – 4.7 (Latest)"https://lab.civicrm.org/documentation/docs-publisher/-/issues/50Allow book versions to be defined in a more flexible way2017-10-19T14:59:04ZSean ColsenAllow book versions to be defined in a more flexible way*Created by: seanmadsen*
## Our current config schema
The way this app currently works, you define a book like this:
```yaml
name: User Guide
langs:
en:
repo: 'https://github.com/civicrm/civicrm-user-guide'
latest:...*Created by: seanmadsen*
## Our current config schema
The way this app currently works, you define a book like this:
```yaml
name: User Guide
langs:
en:
repo: 'https://github.com/civicrm/civicrm-user-guide'
latest: master
stable: 4.7
history:
- 4.6
```
## End-user example from Symfony
There are a number of limitations with our current approach. For the sake of time, I won't summarize them all. But I will offer an example of the end-user experience of choosing a version within [Symfony's documentation](http://symfony.com/doc/current/setup.html):
![screenshot13](https://cloud.githubusercontent.com/assets/42411/23837987/42fc6204-0756-11e7-8ddd-cbf115ca701b.png)
I like the way this works. When you click on "3.2 / Current" you're taken to `/doc/current/`. If you manually enter the URL `/doc/3.2/` you get redirected to `/doc/current`. Very slick. Very usable.
## Proposed new config schema
I want to change it to this:
```yaml
name: User Guide
default_language: en
languages:
en:
repo: 'https://github.com/civicrm/civicrm-user-guide'
default_version: 4.7
watchers:
- sean@seanmadsen.com
versions:
4.7: # This is stored as $slug
name: 4.7 / Current # If omitted, use $slug
path: current # If omitted, use a URL-safe version of $slug
branch: master # If omitted, use $slug
visible: true # If omitted, use "true"
maintained: true # If omitted, use "true"
redirects: # These are not displayed anywhere
- latest
4.6:
branch: 4.6
name: 4.6 / LTS
redirects:
- lts
4.5:
branch: 4.5
visible: false
maintained: false
```
Here's what each of those settings would actually *do*:
- `slug` - basically just used to organize the settings within the yaml file
- `name` - this is what the user sees when choosing between different versions, and at the top of every page when viewing the book
- `path` - this is used for the version component of the URL
- `branch` - tells us what branch to use in the git repo
- `visible` - when true, display this version in lists of different versions presented to the user. When false, don't display this version in navigation, but still allow its content to be published and viewed
- `maintained` - when this is false, display something like "(unmaintained)" to the user in various contexts such as choosing between different versions and (possible) when viewing the book
- `redirects` - when a user requests a URL with one of the listed redirects in place of `path`, the app will redirect the user to the correct URL that uses `path`. Both `branch` and `slug` will automatically function as redirects when their values differ from `path`.
I'm curious to hear feedback from others about this proposal. If I don't hear any concerns within 5 days, I'll begin the work to implement this proposal. https://lab.civicrm.org/documentation/docs-publisher/-/issues/82Books without defined versions should get redirects for "stable", and "current"2017-10-18T21:45:07ZSean ColsenBooks without defined versions should get redirects for "stable", and "current"Reported in this MM thread: https://chat.civicrm.org/civicrm/pl/nt7xmxes4fgk5m45cjcfg17xtc
When a book doesn't define any specific versions we set up one version based on the `master` branch with `latest` in the path. In this situation,...Reported in this MM thread: https://chat.civicrm.org/civicrm/pl/nt7xmxes4fgk5m45cjcfg17xtc
When a book doesn't define any specific versions we set up one version based on the `master` branch with `latest` in the path. In this situation, we should also set up redirects for `stable`, and `current` that take the reader to `latest`.Sean ColsenSean Colsenhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/24The "Publishing" email notificiations should include commit messages2017-10-12T14:36:37ZSean ColsenThe "Publishing" email notificiations should include commit messages*Created by: seanmadsen*
When civicrm-docs publishes a book, it send out an email notification. It would be helpful if, within these email messages, it could include the commit messages (and authors) of the changes published. This way p...*Created by: seanmadsen*
When civicrm-docs publishes a book, it send out an email notification. It would be helpful if, within these email messages, it could include the commit messages (and authors) of the changes published. This way people who didn't make changes but still got the email will see what happened.
This is low priority. Just a thought. michaelmichaelhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/55don't use "admin" as a path component for app functionality2017-10-09T22:42:55ZSean Colsendon't use "admin" as a path component for app functionality*Created by: seanmadsen*
Currently we have these two routes which Symfony handles: `/admin/publish` and `/admin/listen`. I think it's likely that we'll eventually want to have a book with the slug `admin` which complicates this routing....*Created by: seanmadsen*
Currently we have these two routes which Symfony handles: `/admin/publish` and `/admin/listen`. I think it's likely that we'll eventually want to have a book with the slug `admin` which complicates this routing.
I'd like to change those routes to `/system/publish` and `/system/listen` respectively. I think it's unlikely enough that we'll ever want a book with the slug `system`. https://lab.civicrm.org/documentation/docs-publisher/-/issues/68Build books to a temporary directory before publishing2017-10-09T22:39:38ZSean ColsenBuild books to a temporary directory before publishingBuilding books to a temporary directory before publishing will produce a number of improvements.
The description below is specifically about how using temp dirs will help us avoid broken books. But other benefits come with using temp d...Building books to a temporary directory before publishing will produce a number of improvements.
The description below is specifically about how using temp dirs will help us avoid broken books. But other benefits come with using temp dirs as well, which are described in more detail in the comments below
### Steps to reproduce
1. Set up a book which has a broken internal hyperlink in some page content.
1. When you go into this book (outside of docs-publisher) and run `mkdocs serve`, you should see something like this:
```
WARNING - The page "index.md" contained a hyperlink to "documentation.md" which is not listed in the "pages" configuration.
```
1. Get docs-publisher to publish this book.
1. Because we publish with `--strict` (generally good) the `mkdocs build` process will fail
1. After the failure, the published book will be broken.
### Suggested implementation
1. When publishing a book, first set up a temporary directory in which to build the files
1. Run `mkdocs build`
1. If everything goes according to plan, replace the live directory with the newly built directory
1. If any errors are encountered trash the built directory and report the errors
This ticket is a simplification of #39