Custom documentation pages

xAlien95 commented 5 years ago

joshfarrant said: As an aside, I'd also like to come up with a better documentation solution before hitting v1. The current docs are just ok and, while they're better than the previous solution (using jsdoc), they're still not fantastic. I get the feeling we're going to have to roll our own solution, as none of the out-of-the-box options are quite right. Hopefully we'll be able to base this custom solution on the JSON output from typedoc as that won't require any changes to the code, and typedoc is actually pretty good at what it does.

@joshfarrant, in the last couple of days I focused on this bit. I saw that shortcuts.fun has been built with React, so I started to learn it.

I've almost named all the icon glyphs (https://github.com/joshfarrant/shortcuts-js/issues/45) (and I discovered two unpublished ones that works too, red icons are the ones currently without names, I'm at 86.7%):

Metadata page

I also worked on an "Actions" page, in which all the actions should be listed following the sections in the Shortcuts app (I also found some minor errors in https://github.com/joshfarrant/shortcuts-js/issues/6):

Actions page

Since your site is under the following license:

Released under the GNU General Public License v3.0 © 2018 Josh Farrant

I need your approval to publish these documentation pages in this fork.

joshfarrant commented 5 years ago

😍 That looks fantastic! I can’t wait to have a proper look at this!

You’ve just made me realise that the site isn’t particularly clear on the licensing. Currently the site isn’t open sourced just because the code is quick and dirty, but that shouldn’t really stop me making it public, so I’ll take a look at that in a couple of days. The license in the footer of the site is intended to refer to the main Shortcuts JS project (which is GPL-v3), not the actual website. I’ll release the website under MIT as there’s no reason not to. If I do that, you shouldn’t need any special approval to modify it.

What do you need from me for us to look at getting this onto shortcuts.fun?

Happy holidays!🎄

xAlien95 commented 5 years ago

I’ll release the website under MIT as there’s no reason not to. If I do that, you shouldn’t need any special approval to modify it.

Awesome 😀

What do you need from me for us to look at getting this onto shortcuts.fun?

Only your cleverness in web design, I loved how you arranged the site and I would like to get suggestions on the documentation too. I tried to follow your folder scheme, I suppose this shouldn't conflict with your current site (it's my first time with React and Webpack, so I may have done something wrong).

I temporarily edited the docs script to output in /documentation instead of /docs, I also added the following scripts to the package:

docs:json to output the .json in /docs/api/data.json (to be eventually used for our custom documentation)
docs:serve to create the webpack server with hotloading enabled

I'll clear some bits and I'll push this as soon as I can.

Happy holidays! 🎄

EDIT: you can now serve the React site locally using npm run docs:serve. Click on "Documentation [WIP]" in the Jumbotron, "Actions" and "Metadata" are the only pages currently available.

"Actions" contains a list of all the actions dumped from joshfarrant#6. Function names are just evaluated programmatically and they do not currently refer to the actual functions. I have built /Actions/sections.js and /Actions/icons@2x.png with a MatLab script and it's not included in the repo. It will be extremely easy to add the missing icons to the spritesheet. Basically, each number before an action name is the index in the icons@2x.png spritesheet. I plan to add a search bar and infos about the selected action (description, usage example, parameters and a link to that function in the APIs in /docs/api/).
"Metadata" contains all the ordered glyphs currently available in the Shortcuts app with the addition of the unpublished BIKE and TRAIN glyphs (they are the only unpublished glyphs that work). Some icons need to be resized, but that's a pretty good starting point, I think. At the moment there are two different files: /Metadata/gist.js (edited version of my old gist) and /Metadata/glyphs.js. They are split just to make it easier to add names to the missing glyphs.
"Introduction" will contain the installation process via npm and a quick guide on how to install a .shortcut on an iOS device.
"Variables" will contain the four global variables, the actionOutput() and variable() functions as well as the .with() method with some examples.
"Dev Resources" will contain some tips on how to run the linter, the tester, how to set up playground.js and /shortcuts/ folder to store files and how to use scripts/parse.js.

xAlien95 commented 5 years ago

I did some tests in the last couple of hours. The React routing can work on the GitHub Pages repository site, but it requires modifications that won't let webpack-dev-server to work correctly locally. So I decided to remove the GitHub Pages bits from the code.

Users that would like to contribute to the documentation will only have to run npm run docs:serve locally to see actual changes in real time served on http://localhost:3000/.

gcordalis commented 5 years ago

@xAlien95 where did you find the action icons?

xAlien95 commented 5 years ago

... where did you find the action icons?

@gcordalis, Crunch.app can extract compressed assets in the bundled .ipa.

gcordalis commented 5 years ago

This is fantastic! Thanks!

joshfarrant commented 5 years ago

Just so you know @xAlien95, the repo for Shortcuts.fun is now public.

https://github.com/joshfarrant/shortcuts-js-website

joshfarrant commented 5 years ago

I've just got the react app running locally @xAlien95 and it looks great! Very good job reproducing the look of Shortcuts.fun, I'm just sorry it wasn't open-sourced sooner for you to use instead!

The design of the docs so far is really nice, so carry on with exactly what you're doing. I'll gladly take a look at how the data can be generated from the typedoc output if you'd like?

xAlien95 commented 5 years ago

... the repo for Shortcuts.fun is now public.

Thank you!

I've just got the react app running locally @xAlien95 and it looks great!

@joshfarrant, I placed everything in /docs to get it running with GitHub Pages, in that location it's also possible to access all the source code for typedoc. With a separate repo for the website, you need to add the exported .json each time the site has to be updated, but that's not a problem.

I'll fork shortcuts-js-website and I'll work on that.

The design of the docs so far is really nice, so carry on with exactly what you're doing.

I went for a position: fixed container and overflow: scroll children, since on desktop browsers it looks pretty solid. On mobile it doesn't work as hoped, -webkit-overflow-scrolling: touch doesn't work as expected when the contained div reaches the upper and lower bounds of the containing div. Also, I still have to add @media breaks for smaller screens. There's a lot to do and I'll surely request a lot of design feedbacks. 😄

I'll gladly take a look at how the data can be generated from the typedoc output if you'd like?

Thank you, this way you can personally decide what to include and what to not include in the custom api documentation page.

As a side note, are you okay with using React Router for the website? I don't know how you set up your site server-side and if you can apply url rewrites. Also, you went for the subdomain docs.shortcuts.fun for the documentation, so I actually don't know where and how to put the documentation resources in the fork.

joshfarrant commented 5 years ago

I'm happy keeping everything within the /docs directory, rather than forking the project, as it will be simpler to rebuild when the core library changes if we do that.

The other thing I should note is that I'm using Netlify to build/host both the docs and the main website. You shouldn't need to make any special considerations for that, but I thought it might be useful for you to know. That also means that using React Router is fine too.

I'd be happy to take a look at the fixed container styles too 🙂

joshfarrant commented 5 years ago

I meant to mention this morning @xAlien95, I've got the Actions page pulling data from the Typedoc output too.

It's not perfect, but the main structure is there. It has required a couple of changes to the action files though unfortunately, so it might be a bit of a manual process for us to switch it over. For example, the addToVariable action now looks like this:

/** @module actions/actions/scripting/variables/addToVariable */

import Variable from '../interfaces/Variable';
import WFWorkflowAction from '../interfaces/WF/WFWorkflowAction';

/**
 * Add to Variable Action. Appends this action's input to the specified variable, creating the variable if it does not exist.
 *
 * ```js
 * // Append the input to the variable named 'My Var'
 * addToVariable({
 *   variable: variable('My Var'),
 * });
 * ```
 */
const addToVariable = (
  /** The variable to add to */
  options: {
    variable: Variable;
  },
): WFWorkflowAction => {
  const {
    variable,
  } = options;

  return {
    WFWorkflowActionIdentifier: 'is.workflow.actions.appendvariable',
    WFWorkflowActionParameters: {
      WFVariableName: variable.Value.VariableName,
    },
  };
};

export default addToVariable;

export const icon = 86;

The changes are on the first and last lines (maybe we could write something to automate moving it over using your sections.js file?). The @module definition at the top defines the group/category that the item should be placed in, and the exported icon at the end is self-explanatory.

The structure may still change, but at the moment it's working quite well 🙂

xAlien95 commented 5 years ago

@joshfarrant, your solution doesn't specify actual section/groups names. What about this? TypeDoc accepts custom (multiline) tags:

import Variable from '../interfaces/Variable';
import WFWorkflowAction from '../interfaces/WF/WFWorkflowAction';

/**
 * Appends this action's input to the specified variable, creating the variable if it does not exist.
 *
 * ```js
 * // Append the input to the variable named 'My Var'
 * addToVariable({
 *   variable: variable('My Var'),
 * });
 * ```
 *
 * @action Add to Variable
 * @section Actions > Scripting > Variables
 * @section Contents > Something >
 */
const addToVariable = (
  /** The variable to add to */
  options: {
    variable: Variable;
  },
): WFWorkflowAction => {
  const {
    variable,
  } = options;

  return {
    WFWorkflowActionIdentifier: 'is.workflow.actions.appendvariable',
    WFWorkflowActionParameters: {
      WFVariableName: variable.Value.VariableName,
    },
  };
};

export default addToVariable;

This produces the following output in the generated .json:

"comment": {
  "shortText": "Appends this action's input to the specified variable, creating the variable if it does not exist.",
  "text": "```js\n// Append the input to the variable named 'My Var'\naddToVariable({\n  variable: variable('My Var'),\n});\n```\n",
  "tags": [
    {
      "tag": "action",
      "text": "Add to Variable"
    },
    {
      "tag": "section",
      "text": "Actions > Scripting > Variables"
    },
    {
      "tag": "section",
      "text": "Contents > Something >\n"
    }
  ]
},

This let us to add multiple locations for actions that have more (for example, "Markup" is both in "Documents > Editing > Markup" and "Photos & Video > Editing > Markup").

If you would move those @action and @section custom tags up, you have to use a plugin: Single Line Tags.

joshfarrant commented 5 years ago

Ah cool, hadn't realised it supported custom tags, I'll give that a go as I agree it's much nicer 👍

xAlien95 commented 5 years ago

As for the icons, my real sections.js has names instead of icon indexes in the built spritesheet:

const sections = [
  ['Actions', [
    ['Scripting', [
      [null, [
        ['Text', 'Comment'],
        ['Scripting', 'Show Result'],
      ]],
      ['Content', [
        ['Calculator', 'Count'],
        ['Scripting', 'Get Name'],
        ['Scripting', 'Get Type'],
        ['Scripting', 'Nothing'],
        ['Scripting', 'Set Name'],
        ['Graph', 'View Content Graph'],
      ]],
      ...
      ['Device', [
        ['Battery', 'Get Battery Level'],
        ['Network', 'Get Current IP Address'],
        ['Scripting', 'Get Device Details'],
        ['Wi-Fi', 'Get Network Details'],
        ['AirplaneMode', 'Set Airplane Mode'],
        ['Bluetooth', 'Set Bluetooth'],
        ['Brightness', 'Set Brightness'],
        ['CellularData', 'Set Cellular Data'],
        ['DoNotDisturb', 'Set Do Not Disturb'],
        ['Flashlight', 'Set Torch'],
        ['Battery', 'Set Low Power Mode'],
        ['Sound', 'Set Volume'],
        ['Wi-Fi', 'Set Wi-Fi'],
      ]],
...

while the icons images are the following:

Exported assets

If a user has to manually add an icon to a new action, it would be a lot simpler to write something like

/* @icon Scripting

with all the icon .pngs placed somewhere outside of the /docs folder (the website should use the built spritesheet). Should I upload those icons somewhere just for reference? I may alternatively add a subsection on the site in Dev Resources > Contribute > Action Icons with a list of all the icons and their names. This way only the spritesheet icons@2x.png and a built iconImages.js would be needed.

I'm happy keeping everything within the /docs directory, rather than forking the project, as it will be simpler to rebuild when the core library changes if we do that.

I agree for having everything in the /docs folder, but I like how create-react-app handles everything.

How the linter and the node modules would work then? I'll wait for your starting point and I'll use that as a base 🙂

EDIT: I updated this momentaneous fork with a little stupid addition: the calendar action icons is live and reflects the actual date as in the Shortcuts app. I'll remove that if you don't like it. 😄 Bear in mind that this fork is extremely messy, I'll start organizing it when the GUI will be consistent and ready to be coded.

xAlien95 commented 5 years ago

@joshfarrant, I set up a new docs branch in this fork with the addition of the shortcuts-js-website repo as npm package. This way the main package won't be polluted with devDependencies needed for the website. I also added two npm scripts:

npm run docs:json to output the TypeDoc .json in /docs/src/api/data.json;
npm run docs to just run scripts added in /docs/package.json (e.g. npm run docs start will call npm run start on the website package, and so on).

If you prefer having multiple scripts like npm run docs:start, npm run docs:build, etc. I'll add them.

EDIT: I'm removing Typography for two main reasons:

the css isn't applied on the hidden text in CodeMirror editor, so after loading the home page if you place the cursor in the editor, you'll get wrong alignment and selections (it fixes if you resize the window);
Typography injected css can be unpredictable sometimes (as an example, it adds overflow-y: scroll to the html element)

Moreover, a reset.scss could be easily added if needed and dynamic font-sizes can be computed using sass variables.

xAlien95 commented 5 years ago

@joshfarrant, I just updated the docs branch with an initial concept of the Docs > Actions page.

You can run the site with npm run docs start. The following pages are currently available:

Docs > Actions;
Docs > Metadata > Shortcut Icon;
Docs > Contributing > Action Icons: it's just a list of all the available action icon names (the ones in the spritesheet) that will be eventually used via the @icon TypeDoc custom tag.

I'm interested in your thoughts about this and if I can eventually continue on this line.

EDIT: I started parsing action details. What details should be included in your opinion?

xAlien95 / shortcuts-js

Custom documentation pages #1