Documentation Development

This chapter covers the consumption of the documentation, e.g. in an IDE, as well as the development process of the content itself.

• Permanent Links
  • /tB/Core/<Statement>
  • /tB/Modules/<ModuleName>
  • /tB/Core/Attributes#<attribute>
• Development Environment
• Deploying to docs.twinbasic.com
• Editing Screenshots

Permanent Links

The stable, or machine-accessible part of the documentation tree is rooted on the /tB/ prefix. The URLs with this prefix, as well as the internal links (e.g. docs.twinbasic.com/tB/Modules/Math#round), are stable.

/tB/Core/<Statement>

• AppActivate
• Beep
• Call, ChDir, ChDrive, Class, Close, CoClass, Const, Continue
• Date, Declare, Deftype, DeleteSetting, Dim, Do-Loop
• End, Enum, Erase, Error, Event, Exit
• FileCopy, For-Next, Function
• Get, GetSetting, GoSub-Return, GoTo
• If-Then-Else, Implements, Input, Interface, Is
• Kill
• LBound, Let, Line-Input, Load, Lock, LSet
• Mid-equals for Mid(...) = ... , MidB-equals for MidB(...) = ..., MkDir, Module
• Name, New
• Option, On-Error, On-GoSub, On-GoTo, Open
• ParamArray, Print, Private, Property, Public, Put
• RaiseEvent, ReDim, Reset, Resume, RmDir, RSet
• SavePicture, SaveSetting, Seek, Select-Case, SendKeys, Set, SetAttr, Static, Sub, Stop
• Time, Type
• Unload, Unlock
• While-Wend, Width, With, Write

/tB/Modules/<ModuleName>

These are modules within VBA and VBRUN:

• VBA
  • Collection
  • Compilation
  • Constants
  • Conversion
  • DateTime
  • ErrObject
  • ExpressionService
  • FileSystem
  • Financial
  • Information
  • Interaction
  • Math
  • Strings
  • TextEncodingConstants
  • Internal _HiddenModule
• VBRUN
  • AmbientProperties
  • AsyncProperty
  • Constants
  • ContainedControls
  • DataMembers
  • DataObject
  • ErrorCallstack
  • ErrorContext
  • ErrorStackFrame
  • Hyperlink
  • ParentControls
  • PropertyBag

/tB/Core/Attributes#<attribute>

Note

All non-alphabetic characters are removed from the links. All attribute names are in lowercase in the links. I.e. ArrayBoundsChecks(Bool) is referenced as /tB/Core/Attributes#arrayboundschecksbool.

• AppObject
• ArrayBoundsChecks(Bool)
• CoClassCustomConstructor(String)
• CoClassId(String)
• ComCreatable(Bool)
• ComExtensible(Bool)
• ComImport
• CompileIf(Bool)
• ConstantFoldable
• Debuggable(Bool)
• DebugOnly
• Description(String)
• DispId(Integer)
• DllExport
• DllStackCheck(Bool)
• EnumId(String)
• Flags
• FloatingPointErrorChecks(Bool)
• Hidden
• IntegerOverflowChecks(Bool)
• InterfaceId(String)
• OleAutomation(Bool)
• PopulateFrom(…)
• PredeclaredID
• PreserveSig(Bool)
• Restricted
• RunAfterBuild
• SetDllDirectory(Bool)
• TypeHint(EnumType)
• Unimplemented

Development Environment

The documentation is built (renderd to html) using Jekyll.

1. Ensure that Jekyll and Ruby are installed.

   • Installing Jekyll via RubyInstaller on Windows

   Also ensure that Jekyll is in the PATH. To adjust the path on Windows, press ⊞ R, type SystemPropertiesAdvanced  Enter, and click the Environment Variables… button.

2. Fork https://github.com/twinbasic/documentation to your own GitHub account if you plan on making any changes or for convenience. This can be skipped if you just want to build the documentation without changes.

3. Clone either your fork in #2, or the documentation repository itself.

4. Go to the /docs folder in the cloned working tree. Building, serving, and other documentation operations are all done in this folder, not in the repository root.

To build the documentation, i.e. render it from .md files to the _site folder:

bundle exec jekyll build

To build and serve the documentation from http://localhost:4000:

bundle exec jekyll serve

or, on Windows only:

serve.bat

The documentation server detects changes in the filesystem and automatically regenerates the html files as needed. The server does not follow changes in _config.yml. If you change the configuration, the server has to be restarted. Interrupt the server by pressing ^C repeatedly.

To check that none of the internal links in the documentation are broken:

bundle exec htmlproofer ./_site --disable-external --no-enforce-https

or, on Windows only

check.bat

Deploying to docs.twinbasic.com

1. Push your changes to your Github fork of the documentation repository.

2. Open a new pull request in the documentation repository.

3. Click compare across forks.

4. Select your repository and branch to merge from.

   

5. Create the pull request.

   

   A maintainer will merge the pull request into the documentation repository. You may wish to mention an outstanding request on #docs channel, although the #github-docs channel provides automated notifications of pull requests. Normally, a maintainer will get a notification of a new pull request via Discord, and will merge it or comment with a request for changes/improvements.

   The steps below are done by maintainers

6. Review, then merge the pull request or comment with required changes.

   

   

7. Select the Deploy Jekyll site to Pages action.

8. Manually run the build and deployment workflow, as it doesn’t start automatically.

Editing Screenshots

One way of editing screenshots is to use an integrated vector/pixel software like Affinity¹. A possible workflow is:

1. PrtSc to capture the screenshot.

2. In Affinity, Ctrl-Alt-Shift-N (File, New from Clipboard) to get the entire screenshot into the program.

3. Use the Vector Crop tool (from the Vector studio) to crop the screenshot down to the relevant part.

   

4. Select the cropped image, and copy Ctrl-C to clipboard.

5. Create a new file from clipboard again to open a document with just the cropped screenshot in it Ctrl-Alt-Shift-N (File, New from Clipboard).

6. Close the file you opened in #2.

7. Add arrow and labels as needed. Those can be copy-pasted from other .af files in this repository.

8. Export to PNG Ctrl-Alt-Shift-W (File, Export, Export…).

Note

It is a convention to put the .af (“source”) files in the _Images folder, and the exported .png files in the Images folder. Only the latter is published to the website. The former is only to preserve sources for easy editing/updates.

---

¹ Affinity is a free-as-in-beer software that combines the functionality of a vector editor, a bitmap editor, and a publishing layout editor. To download, a Canva account is required. The accounts are free.