New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fixes #4399 - Spacemacs documentation improvements and fixes. #5545

Closed
wants to merge 8 commits into
base: develop
from

Conversation

Projects
None yet
4 participants
@JAremko
Collaborator

JAremko commented Mar 20, 2016

The prime goal of this PR is to fix the Spacemacs documentation links in the Table Of Content at GitHub and introduce reliable method of linking headings from different files that will work in the Spacemacs and both at GitHub and spacemacs.org web sites.

I fixed all the merge conflict except the last commit (it's too global and will constantly brake)

In the discussion #4399 we came to the conclusion that the solution shouldn't modify local files in the Spacemacs installation - they should be the same locally and at the repository. Also we decided to use toc-org for table of content.

Since we can't change how GitHub handles links, I made Spacemacs and spacemacs.org use the GitHub style links - they should always work at GitHub. Also I added some of my PRs that overlaps with this one and smashed bugs, fixed typos that I encountered while implementing the fix. They all are in the separate commits so it shouldn't be a problem.

I'll explain each of the commits



  • Insert the readtheorg.css links wth html export advice 2012530 Many README.org files of the Spacemacs layers have wrong links to the readtheorg.css file. Also it adds unnecessary clutter The commit adds or fixes (if it's already there) the link during the export to html process. Also it implements a wrapper function that can chain all kind of the org file preprocessors (used later)

  • add TOC to Semantic layer bfe1d73 it was missing. Now it's not.

  • Make export to html compatible with GitHub and toc-org d0abe2e this commit adds the export preprocessors:
    • spacemacs//toc-org-unhrefify-toc - makes TOC_gh normal org TOC again.
    • spacemacs//reroot-links - If a link refers an org file or its heading and the file is in the Spacemacs GitHub repository, the function will rewrite the base of the link to http://spacemacs.org/ | example | exported org file.
    • spacemacs//org-heading-annotate-custom-id - adds GitHub style ids to the exported headings so they can be referred in the same way as at the GitHub web site. For the more info read the commit message.

  • Add Spacemacs docs minor mode to hide meta tags. b8f0ea7 When the mode is enabled, it hides nonsense in the docs:
    • Off (the image is clickable)
    • On (the image is clickable)

  • Add org-mode link-type "https" to open local copies 59ae423 this is an org-mode https link type handler that brings GitHub links to the Spacemacs(including links to headings) In a similar fashion to spacemacs//reroot-links if a link refers an org file or its heading and the file is in the Spacemacs GitHub repository, the handler will open the local copy of the file with spacemacs/view-org-file(this is how SPC h SPC opens them) or if it's not in there - the link will be opened in the browser. The function spacemacs/view-org-file applies visual enhancements like the indent mode and space-doc-mode so the opened files also will be prettified. And since those are the GItHub style links they will work at the GitHub, Spacemcs and spacemacs.org. For example:
    • [[https://github.com/syl20bnr/spacemacs/blob/master/doc/FAQ.org#os-x][Link to FAQ "OS X" heading]] leads to (the image is clickable)
    • but [[https://www.google.com][Link to www.google.com]] leads to https://www.google.com
      This is more reliable and flexible way to link files and headings than the default org-mode one - if we want it to work at the GitHub, in the Spacemacs and at its web site. + it adds pretifiers.

  • Remove #+HTML_HEAD_EXTRA: readtheorg.css 100bc0a now we don't need them.

  • Set org files TOC to :TOC_4_gh:noexport: 88e5ff9 This way toc-org will build GitHub TOC when the org files are saved.

  • PR TEST COMMIT 1706d3f toc-org-gh.el script for the applying toc-org to all the org files in the batch mode and example files for the PR. You can call the script from the repo root with find . -name "*.org" -type f -exec emacs -batch -l ./doc/pr-test/toc-org-gh.el '{}' -f toc-apply \;

  • format .org TOCs with toc-org 402bba5 Contains org files processed with toc-org-gh.el - not for merge. Can be easily reproduced by running the script. Probably should be split into a couple of commits, because it makes git crush - too many changes?
This is my magnum opus. Those lines shall be carved on my tombstone 馃槃

@syl20bnr @TheBB @StreakyCobra @a13ph @robbyoconnor @d12frosted and everyone else! Be the witnesses of my glory or the miserable failure!

@JAremko

This comment has been minimized.

Collaborator

JAremko commented Mar 20, 2016

We should discuss it. And if this is a proper way to go around - I'll write about the links in the Contributor guidelines and add .org validations to the Travis test suite.

Also the most of the commits can be safely cherry picked.

(with-temp-buffer
(save-match-data
(insert-file-contents filename t)
(spacemacs//add-org-meta-readtheorg-css filename)

This comment has been minimized.

@syl20bnr

syl20bnr Mar 20, 2016

Owner

You can add a comment here to specify that any preprocess function should be added here.

This comment has been minimized.

@JAremko

JAremko Mar 22, 2016

Collaborator

done.

@syl20bnr

This comment has been minimized.

Owner

syl20bnr commented Mar 20, 2016

A quick look at the PR tells me that it is pretty much what I wanted, nice work 馃憤
Kudos for the script!

@robbyoconnor

This comment has been minimized.

Contributor

robbyoconnor commented Mar 20, 2016

Merge conflicts :P

@JAremko

This comment has been minimized.

Collaborator

JAremko commented Mar 20, 2016

@robbyoconnor Ya it's the last commit. It should be ditched anyway - I have no hope to keep it synced 馃槃

@robbyoconnor

This comment has been minimized.

Contributor

robbyoconnor commented Mar 20, 2016

Not with that attitude you don't!

@JAremko JAremko changed the title from Spacemacs documentation improvements and fixes. to [WIP] Spacemacs documentation improvements and fixes. Mar 21, 2016

@JAremko JAremko changed the title from [WIP] Spacemacs documentation improvements and fixes. to Spacemacs documentation improvements and fixes. Mar 22, 2016

@JAremko

This comment has been minimized.

Collaborator

JAremko commented Mar 22, 2016

@syl20bnr I removed commits that change .org files and improved the formatting script.
Now you just need to run bash ./doc-fmt/run.bash and it will:

  • remove #+HTML_HEAD_EXTRA ... readtheorg.css" />
  • replace :TOC_4_org: with :TOC_4_gh:
  • apply toc-org

This way the PR shouldn't get conflicts so often.

@syl20bnr

This comment has been minimized.

Owner

syl20bnr commented Mar 22, 2016

Great move!

mrclean

JAremko referenced this pull request Mar 23, 2016

README.md: change links to spacemacs.org
Links to documentation sections can easily break since they are
indexed by their order (i.e. #orgheadline8)
@JAremko

This comment has been minimized.

Collaborator

JAremko commented Mar 25, 2016

Dropped add TOC to Semantic layer bfe1d73 because the layer was nuked or moved in develop.

Also squashed my refactorings.

Ahh... The org layer also moved. Cool 馃樋

JAremko added some commits Mar 14, 2016

Insert the readtheorg.css links wth html export advice
It removes the need to clutter Spacemacs documentation with
Also it reduces the amount of bugs, because it's hard to get the path right.
Make export to html compatible with GitHub and toc-org
Add new html preprocessors to the org-html-publish-to-html pipeline:
  - `spacemacs//toc-org-unhrefify-toc` - remove the `toc-org` modifications for the TOC
  - `spacemacs//org-heading-annotate-custom-id` - annotate org headings with the indexes that GitHub uses for linking. `org-html-publish-to-html` will use them instead of the default `#orgheadline{N}`. This way the GitHub links and the http://spacemacs.org/ links will be compatible."
  - `spacemacs//reroot-links` - find the links that start with https://github.com/syl20bnr/spacemacs/blob/ and end with .org{#an-optional-heading-link} (i.e the links between the local org files). Change their root to http://spacemacs.org/ so the links will point at files located on the site.

*For the "file to file" links to work properly the expor
Add Spacemacs docs minor mode to hide meta tags.
`space-doc-mode` - Buffer local minor mode for Spacemacs documentation files. The mode hides org meta tags.
Enabled when viewing documentation via `SPC` `h` `SPC`
Add org-mode link-type "https" to open local copies
The https link-type opens the local copies of the Spacemacs documentation files with
the spacemacs/view-org-file function. It supports GitHub style heading links

For example, the link:

https://github.com/syl20bnr/spacemacs/blob/develop/layers/org/README.org#links

Will be handled similary to as if it was:

file:~/.emacs.d/layers/org/README.org::*links

Also the `space-doc' mode will be applied.

Refactored GH style anchor search.
Add the new .org example and a formatting script
Add ./doc-fmt/ folder that contains the .org example and
the script(run.bash) that should be run from the repo root.
Its purpose:
  - remove  #+HTML_HEAD_EXTRA: ... readtheorg.css" />
  - replace :TOC_4_org:noexport: with :TOC_4_gh:noexport:
  - apply the gh style TOC
update README.org.template to the new convention
Remove #+HTML_HEAD_EXTRA: <link ... /readtheorg.css" />

:TOC_4_org:noexport: -> :TOC_4_gh:noexport:
@JAremko

This comment has been minimized.

Collaborator

JAremko commented Mar 28, 2016

updated README.org.template 4c521bb

@syl20bnr syl20bnr changed the title from Spacemacs documentation improvements and fixes. to Fixes #4399 - Spacemacs documentation improvements and fixes. Mar 30, 2016

@syl20bnr

This comment has been minimized.

Owner

syl20bnr commented Mar 31, 2016

One of my favorite PR, clean and fun to merge. Great job 馃挏
I ran the script on the doc files and it worked great. Also the new preprocessors fixed some wrong CSS paths 馃憤
So this is it, we have links working in Emacs and Github! 馃帀

jaremko

Thank you !
Cherry-picked into develop branch, you can safely delete your branch.

@syl20bnr syl20bnr closed this Mar 31, 2016

@JAremko

This comment has been minimized.

Collaborator

JAremko commented Mar 31, 2016

Thanks! 馃槉

@JAremko JAremko deleted the JAremko:the-big-pull branch Mar 31, 2016

@robbyoconnor

This comment has been minimized.

Contributor

robbyoconnor commented Apr 14, 2016

I love you all

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment