Docs Publisher issues
https://lab.civicrm.org/documentation/docs-publisher/-/issues
2017-10-19T15:15:20Z
https://lab.civicrm.org/documentation/docs-publisher/-/issues/81
Only publish a guide if the docs within its repo have been changed
2017-10-19T15:15:20Z
Sean Colsen
Only publish a guide if the docs within its repo have been changed
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 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_McAndrew
https://lab.civicrm.org/documentation/docs-publisher/-/issues/80
Editing non-master branches with the pencil icon doesn't work
2017-10-19T15:10:25Z
Sean Colsen
Editing non-master branches with the pencil icon doesn't work
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/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.md
https://lab.civicrm.org/documentation/docs-publisher/-/issues/51
User Guide - label 4.7 as "Latest" and 4.6 as "LTS"
2017-10-19T15:00:17Z
Sean Colsen
User 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/50
Allow book versions to be defined in a more flexible way
2017-10-19T14:59:04Z
Sean Colsen
Allow 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/82
Books without defined versions should get redirects for "stable", and "current"
2017-10-18T21:45:07Z
Sean Colsen
Books 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 Colsen
Sean Colsen
https://lab.civicrm.org/documentation/docs-publisher/-/issues/24
The "Publishing" email notificiations should include commit messages
2017-10-12T14:36:37Z
Sean Colsen
The "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.
michael
michael
https://lab.civicrm.org/documentation/docs-publisher/-/issues/55
don't use "admin" as a path component for app functionality
2017-10-09T22:42:55Z
Sean Colsen
don'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/68
Build books to a temporary directory before publishing
2017-10-09T22:39:38Z
Sean Colsen
Build books to a temporary directory before publishing
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 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
https://lab.civicrm.org/documentation/docs-publisher/-/issues/78
Allow books to define redirects which point to other books
2017-09-24T00:13:55Z
Sean Colsen
Allow books to define redirects which point to other books
Modify the internal redirect functionality to allow each book to define *external* redirects in the `redirects/internal.txt` file.
(I realize it won't be very intuitive to put external redirects in a file called `internal.txt`, but I th...
Modify the internal redirect functionality to allow each book to define *external* redirects in the `redirects/internal.txt` file.
(I realize it won't be very intuitive to put external redirects in a file called `internal.txt`, but I think it's worth it to live with this unfortunate consequence. In the future we could change the app to first look for a file with a different name.)
https://lab.civicrm.org/documentation/docs-publisher/-/issues/71
Update information in the footer/bottom area
2017-07-31T16:05:29Z
josh
josh@civicrm.org
Update information in the footer/bottom area
Would be good to add in a footer consistent with civicrm.org:
© 2005 - 2017, CIVICRM LLC. All rights reserved.
CiviCRM and the CiviCRM logo are trademarks of CIVICRM LLC. Except where otherwise noted, content on this site is licensed un...
Would be good to add in a footer consistent with civicrm.org:
© 2005 - 2017, CIVICRM LLC. All rights reserved.
CiviCRM and the CiviCRM logo are trademarks of CIVICRM LLC. Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution-Share Alike 3.0 United States Licence.
Also, might be nice to expand on the content to "support" (http://civicrm.org/support-us) CiviCRM. Some might want to help with documentation whereas others might want to make a small gift.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/22
Provide language and version switching capability within books
2017-04-30T22:16:43Z
Sean Colsen
Provide language and version switching capability within books
*Created by: seanmadsen*
The User Guide has multiple versions and multiple languages, all of which are listed on https://civicrm.org/documentation but many URLs for this guide point only to the latest English version at https://docs.civ...
*Created by: seanmadsen*
The User Guide has multiple versions and multiple languages, all of which are listed on https://civicrm.org/documentation but many URLs for this guide point only to the latest English version at https://docs.civicrm.org/user/en/latest/. Once a reader arrives there, it is not apparent that they have the option to read the guide in other languages or for other versions.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/23
"Edit on GitHub" should take user to specific page
2017-04-30T22:16:43Z
Sean Colsen
"Edit on GitHub" should take user to specific page
*Created by: seanmadsen*
When reading a guide book, the reader/user can click a link at the top right to "Edit on GitHub". This link takes the user to the root of the GitHub repository. From that point, the user does not have an intuiti...
*Created by: seanmadsen*
When reading a guide book, the reader/user can click a link at the top right to "Edit on GitHub". This link takes the user to the root of the GitHub repository. From that point, the user does not have an intuitive way of finding the page to edit. It would be nice if the "edit" link took the user to edit exactly the page being viewed.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/25
Clarify role (user / admininstrator / developer) terminology
2017-04-30T22:16:43Z
Sean Colsen
Clarify role (user / admininstrator / developer) terminology
*Created by: michaelmcandrew*
The words user and developer are pretty clear.
Administrator is ambigious since it can refer to
* an advanced user that sets things up for other users using the UI
* a system administrator that doe...
*Created by: michaelmcandrew*
The words user and developer are pretty clear.
Administrator is ambigious since it can refer to
* an advanced user that sets things up for other users using the UI
* a system administrator that does stuff like install, host, and is familiar with CLI, SSH, FTP, DNS, etc.
I'm not sure that coming up with a rule like "administrator MUST only be used to signify system administrator" is a good idea since language is nuanced. On the other hand, if we could could up with an acceptable phase for an "advanced user that does set up" that might change my mind.
Alternatively, just some sensible guidance on how we refer to different roles would be good to have in the documentation guidelines.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/26
home page - add some more info about docs, generally
2017-04-30T22:16:43Z
Sean Colsen
home page - add some more info about docs, generally
*Created by: seanmadsen*
If we want to redirect civicrm.org/documentation to docs.civicrm.org eventually, we'll need some more info on the docs home page.
Michael [said](https://github.com/civicrm/civicrm-docs/issues/18#issuecomment...
*Created by: seanmadsen*
If we want to redirect civicrm.org/documentation to docs.civicrm.org eventually, we'll need some more info on the docs home page.
Michael [said](https://github.com/civicrm/civicrm-docs/issues/18#issuecomment-273431305) It does need a bit of fleshing out. Copying content from http://civicrm.org/documentation to https://github.com/civicrm/civicrm-docs/blob/master/src/AppBundle/Resources/views/Read/home.html.twig
https://lab.civicrm.org/documentation/docs-publisher/-/issues/27
Home page - improve visual style
2017-04-30T22:16:43Z
Sean Colsen
Home page - improve visual style
*Created by: seanmadsen*
Would be great to get the branding on the docs home page to match that on civicrm.org. For example, putting the logo up there, and using the same font, colors, etc.
*Created by: seanmadsen*
Would be great to get the branding on the docs home page to match that on civicrm.org. For example, putting the logo up there, and using the same font, colors, etc.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/28
Home page - books missing
2017-04-30T22:16:43Z
Sean Colsen
Home page - books missing
*Created by: seanmadsen*
In my local installation of civicrm-docs I see a home page which lists the User Guide but does not list the Dev Guide. When I publish all books via command line the Dev Guide is include in this publishing proces...
*Created by: seanmadsen*
In my local installation of civicrm-docs I see a home page which lists the User Guide but does not list the Dev Guide. When I publish all books via command line the Dev Guide is include in this publishing process, so the app is well aware of the existence of the Dev Guide. Tim also [observed](https://chat.civicrm.org/civicrm/pl/7fh9y7w5o7d458yukjsuf33mby) the same behavior.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/30
Create book categorization functionality
2017-04-30T22:16:43Z
Sean Colsen
Create book categorization functionality
*Created by: seanmadsen*
I would like for civicrm-docs to be capable of hosting extension-specific books eventually. I can imagine a day when there are a handful of books core-related books (e.g. User, Admin, Dev), plus over a dozen ext...
*Created by: seanmadsen*
I would like for civicrm-docs to be capable of hosting extension-specific books eventually. I can imagine a day when there are a handful of books core-related books (e.g. User, Admin, Dev), plus over a dozen extension-specific books. When this day comes, having a docs home page that separates core-related books from extension-specific books will make the home page easier to navigate.
I propose the following is added to a book's `.yml` config file:
```yaml
category: core
```
or
```yaml
category: extension
```
If this setting is missing, then the app would assume "extension".
After these categories are in place, the home page can be modified to display books separately by category.
Why do this now, when there are zero extension-specific books? — I think that if we can get *one* extension-specific book in there and make the home page look really slick and well-organized, it will help motivate other extensions maintainers to set up their own docs in books.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/31
Create book sorting functionality
2017-04-30T22:16:43Z
Sean Colsen
Create book sorting functionality
*Created by: seanmadsen*
Currently the home page lists books alphabetically. I'd like to eventually show books in the following order:
* User Guide
* Administrator Guide
* Developer Guide
I'm proposing adding a new configuratio...
*Created by: seanmadsen*
Currently the home page lists books alphabetically. I'd like to eventually show books in the following order:
* User Guide
* Administrator Guide
* Developer Guide
I'm proposing adding a new configuration value to each book's `.yml` file as follows:
```yaml
weight: 2
```
Then books could be assigned specific weights and ordered as such.
https://lab.civicrm.org/documentation/docs-publisher/-/issues/32
Migrating content from stack exchange to docs
2017-04-30T22:16:43Z
Sean Colsen
Migrating content from stack exchange to docs
*Created by: michaelmcandrew*
It strikes me that Stack Exchange is potentially a great source of inspiration / content for our documentation. http://civicrm.stackexchange.com/questions?sort=votes has a list of topics that we should ensu...
*Created by: michaelmcandrew*
It strikes me that Stack Exchange is potentially a great source of inspiration / content for our documentation. http://civicrm.stackexchange.com/questions?sort=votes has a list of topics that we should ensure are represented in the docs.
I imagine post popular *answers* as well would be useful but I can't find the an appropriate URL for that.
We can use the content from SE as (a starting point) for the actual text, and link to the docs from a comment on the question / answer, if relevant.
Not sure what labels to attach to the issue, but thought it was worth capturing / discussing...
https://lab.civicrm.org/documentation/docs-publisher/-/issues/33
How will users switch between different versions of a book?
2017-04-30T22:16:43Z
Sean Colsen
How will users switch between different versions of a book?
*Created by: seanmadsen*
@nganivet [raised the issue](https://github.com/civicrm/civicrm-docs/issues/15#issuecomment-275983259) of documentation users needing a clear and usable way to switch between different versions of a book. For ex...
*Created by: seanmadsen*
@nganivet [raised the issue](https://github.com/civicrm/civicrm-docs/issues/15#issuecomment-275983259) of documentation users needing a clear and usable way to switch between different versions of a book. For example if a user lands on the User Guide for CiviCRM 4.6, how does this user switch to the User Guide for the most current version? What indication does the user even have that they could potentially be reading an outdated version of the docs?
@nganivet included this screedshot in the original discussion as an example:
![screenshot](https://cloud.githubusercontent.com/assets/3435067/22413152/9cb83444-e672-11e6-97e2-77081c3aab79.png)