Documentation update: Fixes issue #1557#1662
Documentation update: Fixes issue #1557#1662sugar700 merged 85 commits intofish-shell:masterfish-shell/fish-shell:masterfrom MarkGriffiths:documentation-updateCopy head branch name to clipboard
Conversation
Rework for Doxygen >1.8. Moved large parts of the documentation to a simplified format, making use of Markdown enhancements and fixing bad long options.
Subllime and a few temporary files.
Conflicts: doc_src/history.txt doc_src/test.txt
Addresses issue #1557 as well as fixing many typos, HTML errors and inconsistencies. Also introduces automatic syntax colouring and enables new documentation to be written in Markdown. TODO fix Tutorial.
Fixed manpage 'NAME'. Under Doxygen 1.8, the output format has changed, so the old sed script was leaving man pages with two titles.
Conflicts: doc_src/index.hdr.in -- UPDATED doc_src/license.hdr -- UPDATED
This reverts accidentally included files in commit 60b9f8d.
If the lexicon input filter isn't specified (as is the case in the current Xcode project, the script quietly continues without it.
Completely fixes #1557 and the underlying Doxygen changes that caused it. Should make fish docs simpler and more robust, more consistent and generally prettier. todo: - trap unmarked text as arguments in context - test & fix sed portability - see in particular. (so far tested on BSD (Mac) and GNU sed). - test Makefile changes - last round of aesthetic changes and getting that ascii fish in there…
Conflicts (FIXED): .gitignore doc_src/complete.txt doc_src/function.txt
Conflicts (FIXED): doc_src/command.txt doc_src/index.hdr.in doc_src/read.txt doc_src/type.txt
+ small fixes
|
Done, and preview links above updated. Full rationale/style guide in user_doc/FORMATTING.md (also posted in issue #1557) |
|
Approved 👍. Normally, I would merge a commit after approving it. However, this is a big change (24,380 new lines is huge, even if there is a good reason for that), so I would prefer to wait with merging for other fish shell contributors to approve this particular pull request. |
|
Totally understandable. It took that amount of editing to catch everything in doc_src - mind you, just the three updated Doxyfiles account for ~6000 lines of changes! |
|
14425 of the added lines are a brand new Portuguese translation file, which apparently comes from the merge of master into this branch. |
|
More generally, |
There was a problem hiding this comment.
This should probably be cd user_doc/html && rm -f ..., no? That way if the user_doc folder fails to be created in the first place, this won't attempt to delete files in the current directory.
|
Aside from the couple of |
.Conflicts (resolved): doc_src/design.hdr - \c changed to backticks
|
At this point I'm inclined to merge it, the only thing stopping me from hitting the switch right now is the fact that Doxygen 1.8.7 is not available by default on Ubuntu 14.04 and earlier, and likely other Linux distros as well. I'm not sure what process is used to build the nightlies or full releases, and whatever that process is, it needs to be able to build the docs. @ridiculousfish or someone else who knows, is the Doxygen 1.8.7 requirement an issue or is this good to merge? |
|
I wouldn't mind the chance to test it because I suspect the nightly builds will stop generating documentation. |
|
OK, this definitely doesn't support 1.8.1.2 (which is in Debian Stable) - |
|
I tried 1.8.6 under Ubuntu and found that Doxygen is missing the new \htmlonly[block] directive which came in under 1.8.7 (the version that homebrew installed when I began working on this). The result of this was the word 'block' appearing at the top of each semantic block, i.e. the top of each page and above \fish blocks. \htmlonly[block] is important for the docs as it keeps the block elements in the HTML output in the structural order expressed in the source (similar to using \parblock, but smarter) and it fixed many HTML structural issues that were present in the old documentation. Personally, I've been waiting for this feature for a long time! In my own testing on Ubuntu and CentOS I had to build Doxygen (1.8.8) from GitHub source. I was hoping that as fish ships with prebuilt documentation that this wouldn't have been too much of an issue. |
|
It certainly does ship with prebuilt documentation; my concern is the raising of the barrier for contributing to the documentation. However there are prebuilt binaries available on the Doxygen website so I think it would be reasonable to expect people to be able to download them. I think Markdown lowers the bar for contributing and I am very grateful for that! Let's merge. |
Documentation update: Fixes issue #1557
|
\o/ This is awesome! |
|
Holy cow! |
|
Yikes. I just noticed the license on some of the files. Would you consider relicensing |
|
I don't consider it a serious or formal license in any way at all - it's simply intended as a tongue-in-cheek way of saying "blimey, I've spent far too much time, missed too much sleep and drunk too much coffee getting this right than would be considered sane, yet it's my gift to the fish community so I'd better say something...". My intention is that it should fall under fish's license completely and unreservedly. Apologies if that didn't come across, I simply hoped it would raise a smile, and in 20+ years of publishing software and digital media I've never had to enforce a license... British humour I guess 😉 I'm happy for that to be completely stripped out or modified in any way to make it clear. That said, I felt it should say something as the filter's mechanism is fairly novel and self-contained and demonstrates how to create custom syntax colouring in Doxygen using an input filter - something often asked for in the Doxygen community, but rarely answered. It would be a useful template for others to start from. |
|
That would be great. Would you forgive me for being the Fun Police and raise a PR with that change? It just needs to say "this code is licensed with fish under the GPL 2.0" but I would be happier if the commit had your authorship on it! |
Output preview: