Reorganize project for documentation via gitbook #158
Conversation
+ Replaced all restructured text files with markdown files, transitioning the markup between them to keep the content equivalent. + Added scaffolding, including project build script and accompanying psake tasks, for managing project documentation via gitbook. + Updated `.gitignore` for the new file types and output. + Removed extraneous image and media folder not currently in use. + Tasks for documentation auto-generate reference docs for functions and tests based on the captured information from those files. Related Issue: #70, #104
|
You can find a live preview of the generated docs here: |
michaeltlombardi
changed the title
+ The CHANGELOG used a `:heart:` instead of a unicode character; this only works in GFM, and so did not translate to documentation. Updated the header to use the unicode heart instead. + The CHANGELOG has numerous referenced issues but github does not link to the filed issues natively. Additionally, the CHANGELOG display was broken in GitBook due to a mis-parsing of the issues as headers. Here we turned each issue into an explicit link to the upstream issue tracker and fixed both problems at once.
|
Second commit fixed some problems I missed with the change log, those should be resolved now. |
michaeltlombardi
changed the title
+ Test reference docs used the test-file name for their first level header and file name in documentation. This is problematic because it assumes that the test file name was written to be easily and cleanly human-parsable. That is not the case for numerous tests. Updating the psake task for the reference docs makes them easier to discover and easier to understand.
There was a problem hiding this comment.
🔥, seriously! I'm going to play around with the build/psake files to understand exactly how the build process works here.
I imagine I'll merge this tonight or tomorrow, in case I think of any questions, and as a last opportunity for other interested parties to comment.
|
Awesome! Let me know what, if any, issues you run into. A good follow-up issue to this would be a concept doc around the build file. Loosely, the psake tasks define a way for the executor to install the needed powershell modules, install chocolatey, use chocolatey to install software, and install npm packages - that covers the software prereqs we can't assume will be on every machine. The project-specific tasks are more around the |
|
The basics, outputting # This will install PS modules, gather environment info, and then call psake.ps1
# If you run this locally, Posh needs admin rights for Chocolatey/NodeJS/etc. installs
.\build.ps1 -TaskList Compile
# EDIT 2017/08/21 - See #169 for a slight update on thisThe whole nine yards for any interested parties to investigate on their own; creates a PDF (lol awesome) in the project root, and also serves up the site at .\build.ps1 -TaskList Compile,GenerateSite,GeneratePdf,LivePreview
|
|
Let it be known that on Tuesday, June 20th, 2017, technology won the day. There will be more battles on the road ahead, and you may grow weary yet. But for tonight, we will revel in our victory, and reflect on the sacrifices of others so that we may fully appreciate this achievement. |
.gitignorefor the new file types and output.Related Issues: #70, #104