Add a tool to generate absolute links in online docs

This allows us to use /-paths for images and internal
links, and still have working paths in HTML, regardless
of the hosting path. This also adds a switch for debug
and production documentation builds, so local
testing is not broken.

Author: YuriSizov

docs/README.md

@@ -33,13 +33,13 @@ If you want to insert an image, add it to the `/assets/images` folder first and
 So if your image is at `/assets/images/bosca-is-awesome.png`, use
 
 ```md
-![](images/bosca-is-awesome.png)
+![](/images/bosca-is-awesome.png)
 ```
 
 And if the article that you want to link is at `/src/another-article.md`, use
 
 ```md
-Read in [another article](another-article.md)
+Read in [another article](/another-article.md)
 ``` 
 
 If you want to add a new article, place and `.md` file in the `/src` folder. Use the root of the `/src` folder for top-level articles (the ones that go into the sidebar navigation). Put other articles into subfolders according to their topic (you can create a new one if necessary).

docs/build.py

@@ -6,12 +6,14 @@
 
 # Main docs builder script.
 
+import argparse
 from pathlib import Path
 from os import walk
 import shutil
 
 import markdown
-from colorize import magenta, cyan, yellow, green, gray, bold
+from tools.colorize import magenta, cyan, yellow, green, gray, bold
+from tools.paths import MarkdownPaths
 
 # Paths.
 DOCS_SOURCE = "./src"
@@ -46,11 +48,22 @@
 }
 ALL_PAGES = []
 
+LINK_BASE_PATH = "http://localhost:8080"
+
+
+# Command line arguments.
+parser = argparse.ArgumentParser()
+parser.add_argument("--release", action="store_true", help="Enables release-mode settings.")
+args = parser.parse_args()
+
+if args.release:
+    LINK_BASE_PATH = "https://humnom.net/apps/boscaceoil/docs"
+
 # Instance of the markdown builder. We enabled several extensions by default:
 # - The meta extension allows to extract frontmatter-like metadata.
 # - The tables extension enables syntax for tables.
 # - The toc extension adds support for a table of content, and gives headings unique ids.
-builder = markdown.Markdown(extensions=['meta', 'tables', 'toc'])
+builder = markdown.Markdown(extensions=['meta', 'tables', 'toc', MarkdownPaths(base=LINK_BASE_PATH)])
 
 
 # Helpers.

docs/src/arrangements.md

@@ -6,7 +6,7 @@ title: Arrangements
 
 Now that you've mastered working with notes, the next step is making more patterns and arranging them into a song. Conveniently, you can find the necessary tools in the `ARRANGEMENT` view!
 
-![](images/overview-arrangement-view.png)
+![](/images/overview-arrangement-view.png)
 
 This panel has 3 major parts: the pattern dock, the arrangement grid, and the timeline. Let's take on them in order.
 
@@ -15,15 +15,15 @@ This panel has 3 major parts: the pattern dock, the arrangement grid, and the ti
 
 On the right side of the arrangement view is a panel where you will immediately find one blue rectangle with a number and perhaps some dots. Below it, at the bottom of the panel, is the `ADD NEW` button. This is the pattern dock, a list of all patterns that you currently have made for your song. Clicking on the button will, predictably, add a new pattern, and once there are too many of them, buttons for scrolling the list will appear. You can also scroll with your <kbd>Mouse Wheel</kbd>.
 
-![](images/arrangements-dock.png)
+![](/images/arrangements-dock.png)
 
 To delete a pattern completely, simply <kbd>Left Click</kbd> and start dragging it. Shortly after, a new label will appear beneath the dock that reads `DELETE?`. Drop the pattern on that label, and it will be deleted. If this pattern is used by the song, it will disappear from the arrangement, replaced by emptiness.
 
-![](images/arrangements-dock-delete.png)
+![](/images/arrangements-dock-delete.png)
 
 With the basics of pattern management out of the way, it's time to start composing. Once again, <kbd>Left Click</kbd> and drag the pattern, but this time move it to the left side where the arrangement grid is visible. At this point you can see a similar blue rectangle occupying the top-left cell. Drop the pattern into the next cell to add it to the song.
 
-![](images/arrangements-drag-n-drop.png)
+![](/images/arrangements-drag-n-drop.png)
 
 There can be only 4096 unique patterns in a song.
 
@@ -32,24 +32,24 @@ There can be only 4096 unique patterns in a song.
 
 Just like notes in patterns conform to a metronome, ticking away at regular intervals, the entire song conforms to the same metronome as well. The arrangement grid in front of you represents the chronological order of patterns in your song, with each column corresponding to a pattern-sized unit of time called _a bar_. Bars are further split into 8 rows, called channels or tracks. This gives you the means to play up to 8 unique patterns at the same time.
 
-_Bosca Ceoil Blue_ automatically keeps track of every bar that you fill with patterns, and when the time comes to [export your song](export_import.html), everything that you've added up to that moment will be included. Keep in mind, that the maximum length of any song is 1000 bars.
+_Bosca Ceoil Blue_ automatically keeps track of every bar that you fill with patterns, and when the time comes to [export your song](/export_import.html), everything that you've added up to that moment will be included. Keep in mind, that the maximum length of any song is 1000 bars.
 
 To add a pattern to the arrangement, drag and drop it from the pattern dock, or <kbd>Left Click</kbd> and drag one of the existing patterns on the grid onto another cell, making a copy. Hold <kbd>Alt</kbd> as you do this, and instead of a copy a new variant of the original pattern will be created. You can also simply <kbd>Alt + Left Click</kbd> on a pattern to turn it into a variant.
 
 <kbd>Right Click</kbd> removes the clicked pattern from the grid. This doesn't delete the pattern, however, and you can still use it later.
 
-![](images/arrangements-patterns.png)
+![](/images/arrangements-patterns.png)
 
-A pattern that has a reddish frame around it is selected for editing. This is the pattern that you see below, in the [pattern editor](notes_and_patterns.html). Any time you <kbd>Left Click</kbd> a pattern or create a new pattern by any means, that pattern gets selected.
+A pattern that has a reddish frame around it is selected for editing. This is the pattern that you see below, in the [pattern editor](/notes_and_patterns.html). Any time you <kbd>Left Click</kbd> a pattern or create a new pattern by any means, that pattern gets selected.
 
-The grid can be scrolled through with <kbd>Mouse Wheel</kbd> or a [keyboard shortcut](shortcuts.html). On top of that, you can change the scale of the grid, making it more compact or more spacious, by holding <kbd>Ctrl</kbd> as you scroll.
+The grid can be scrolled through with <kbd>Mouse Wheel</kbd> or a [keyboard shortcut](/shortcuts.html). On top of that, you can change the scale of the grid, making it more compact or more spacious, by holding <kbd>Ctrl</kbd> as you scroll.
 
 
 ## Timeline
 
 Below the arrangement grid you can find an extra row with numbers, and a white line crossing through some of the cells. This is the arrangement timeline, a tool that lets you control the parts of the song that are being played. With a <kbd>Left Click</kbd> on any of the cell, you can select the corresponding bar for playback. Hold the mouse button and drag across several cells to select a whole range, or <kbd>Double Click</kbd> on a cell to select every bar from this to the very end.
 
-![](images/arrangements-timeline-select.png)
+![](/images/arrangements-timeline-select.png)
 
 The bars selected this way do not affect the export. This is purely a tool for you to preview portions of your song. But the timeline itself can do more than that.
 
@@ -58,4 +58,4 @@ The bars selected this way do not affect the export. This is purely a tool for y
 
 ## Managing instruments
 
-The next step is all about building and tuning your instrument set. Onto the [Instruments](instruments.html)!
+The next step is all about building and tuning your instrument set. Onto the [Instruments](/instruments.html)!

docs/src/effects.md

@@ -6,7 +6,7 @@ title: Effects
 
 While individual instruments only allow you to configure a low-pass filter to adjust their sound, a variety of more interesting effects can be applied to the song overall. You can find these extra effects and filters in the `ADVANCED` view.
 
-![](images/overview-advanced-view.png)
+![](/images/overview-advanced-view.png)
 
 
 ## Global effects
@@ -30,12 +30,12 @@ Typically, many of these effects allow for a very granular control via a number
 
 Separate from other effects is _swing_. Using _swing_ you can adjust the timing of the played notes. Normally, a note in _Bosca Ceoil Blue_ can be played at every tick of the metronome. The swing effect takes two consecutive notes in a pattern and adjusts their proportions, such that one of the notes takes the majority of their combined time and the other takes the minority.
 
-![](images/effects-swing.png)
+![](/images/effects-swing.png)
 <span class="caption">A rough demonstration of how note timings change with swing; in the app itself the notes' visuals remain unchanged when you adjust swing.</span>
 
 In other words, if two notes take _two ticks_ to play, then adjusting the swing effect to the left makes the first note take the smaller portion of those two ticks, and the second note — to take the larger portion. Moving the slider to the right does the opposite, and the first note takes the larger portion.
 
 
 ## Exporting results
 
-Now that we've got every part of the creative process covered, it's time to render the song for the world to hear! Read on in [Export and Import](export_import.html).
+Now that we've got every part of the creative process covered, it's time to render the song for the world to hear! Read on in [Export and Import](/export_import.html).

docs/src/export_import.md

@@ -22,7 +22,7 @@ Regardless of the format, during the export process you can configure a number o
 
 - **Export bars** allows you to define the range, in arrangement bars, that is going to be exported. By default the entire song is exported, but you might need to only export a part of it, which is where this option becomes helpful.
 
-![](images/io-export.png)
+![](/images/io-export.png)
 
 ### Limitations
 
@@ -65,7 +65,7 @@ If you're a daring soul, you might want to try importing a MIDI file into _Bosca
 
 This means that we cannot support multiple time signatures and tempos, as well as any command that doesn't perfectly map to metronome ticks. Within these limitations, you should have decent luck importing songs into the app this way. And on the plus side, _Bosca Ceoil Blue_ supports all standard MIDI instruments, including drumkits.
 
-![](images/io-import.png)
+![](/images/io-import.png)
 
 Several configuration options are available for you when importing songs:
 

docs/src/index.md

@@ -8,9 +8,9 @@ _[bús-ka kyó-al] — a music box._
 
 **Bosca Ceoil: The Blue Album** (or _Bosca Ceoil Blue_, for short) is a simple and beginner-friendly app for making music. Using a step sequencer you can create anything from a simple beat to a complex melodic piece — with huge selection of synthesized instruments at your disposal!
 
-The best place to start learning about _Bosca Ceoil Blue_ and its features is the [Overview](overview.html) page.
+The best place to start learning about _Bosca Ceoil Blue_ and its features is the [Overview](/overview.html) page.
 
-![](images/introduction-welcome.png)
+![](/images/introduction-welcome.png)
 
 
 ## Version compatibility
@@ -24,7 +24,7 @@ Versions prior to 3.0 (i.e. original _Bosca Ceoil_) are not covered by this docu
 
 ## Available languages
 
-_Bosca Ceoil Blue_ is available in **English**, and so is this documentation. If you have made a tutorial or an overview of the app in your native language, please feel free to add a link to it to the [Community](community.html) page.
+_Bosca Ceoil Blue_ is available in **English**, and so is this documentation. If you have made a tutorial or an overview of the app in your native language, please feel free to add a link to it to the [Community](/community.html) page.
 
 
 ## Contributing

docs/src/instruments.md

@@ -8,14 +8,14 @@ The second most important tool after the arrangement view is the `INSTRUMENT` vi
 
 In _Bosca Ceoil Blue_ you can find hundreds of instrument presets, but instead of using them directly you first must create a song instrument out of one of them. This allows you to quickly find the instrument that you need when editing patterns, and to use the same preset multiple times with different tuning configurations.
 
-![](images/overview-instrument-view.png)
+![](/images/overview-instrument-view.png)
 
 
 ## Instrument management
 
-The instrument view is split into two parts: the instrument dock and the instrument configuration panel. Similarly to how you can create and delete patterns from the dock in the [arrangement view](arrangements.html), you can create and delete instruments from the instrument dock. Pressing `ADD NEW INSTRUMENT` adds a random instrument to the list, while dragging and dropping one of the existing instruments onto the `DELETE?` label deletes it.
+The instrument view is split into two parts: the instrument dock and the instrument configuration panel. Similarly to how you can create and delete patterns from the dock in the [arrangement view](/arrangements.html), you can create and delete instruments from the instrument dock. Pressing `ADD NEW INSTRUMENT` adds a random instrument to the list, while dragging and dropping one of the existing instruments onto the `DELETE?` label deletes it.
 
-![](images/instruments-dock-delete.png)
+![](/images/instruments-dock-delete.png)
 
 You can only create up to 16 unique instruments.
 
@@ -37,7 +37,7 @@ Instruments are grouped into several categories, with the MIDI set being split e
 - World
 - Drumkit
 
-![](images/instruments-categories.png)
+![](/images/instruments-categories.png)
 
 And the following are sub-categories of MIDI instruments:
 
@@ -60,9 +60,9 @@ And the following are sub-categories of MIDI instruments:
 
 Instruments are loosely color-coded, which not only makes _Bosca Ceoil BLue_ look fun and appealing, but also helps you to distinguish them. The instrument used also defines the color of the pattern, as you might've noticed already.
 
-Once created, the instrument can be selected for any pattern using the list in the bottom-left corner of the [pattern editor](notes_and_patterns.html).
+Once created, the instrument can be selected for any pattern using the list in the bottom-left corner of the [pattern editor](/notes_and_patterns.html).
 
-![](images/instruments-pattern-picker.png)
+![](/images/instruments-pattern-picker.png)
 
 
 ## Tuning
@@ -71,7 +71,7 @@ One way to further define the voice of the instrument that you've selected is to
 
 The low-pass filter may require a bit of an explanation. Controlled with a pad rather than a 1-dimensional slider, this filter has two parameters, resonance and cutoff. Moving the pad head left and right adjusts the cutoff point, while moving it up and down changes the resonance.
 
-![](images/instruments-tuning-pads.png)
+![](/images/instruments-tuning-pads.png)
 
 The low-pass filter, as the name suggests, allows audio frequencies below the cutoff threshold to pass freely, while damping those that go beyond that limit. In other words, the further left you move the pad head, the less high-frequency sounds will be allowed by the instrument.
 
@@ -84,15 +84,15 @@ Some sounds produced this way may be unpleasant, especially at extreme values. P
 
 ## Instrument recording
 
-You can push instrument tuning even further than that! At the bottom of the [pattern editor](notes_and_patterns.html) there is a mysterious `REC` button with a round icon. When clicked, the icon turns red and the instrument view opens — on the instrument that the edited pattern uses. A pinkish label `! RECORDING: PATTERN N !` also appears, as the tuning pads get a similarly pinkish frame.
+You can push instrument tuning even further than that! At the bottom of the [pattern editor](/notes_and_patterns.html) there is a mysterious `REC` button with a round icon. When clicked, the icon turns red and the instrument view opens — on the instrument that the edited pattern uses. A pinkish label `! RECORDING: PATTERN N !` also appears, as the tuning pads get a similarly pinkish frame.
 
-![](images/instruments-recording.png)
+![](/images/instruments-recording.png)
 
 This feature is called instrument recording, and what it allows you to do is to set specific values for the low-pass filter and volume of the instrument for each individual tick of the pattern.
 
 While the recoding mode is enabled and the pattern is being played through, start changing the values using the tuning pads. As you move a pad head, you should notice a colorful trail that is left by it. Those are the values recorded for each note of the pattern, color-coded from red to green.
 
-![](images/instruments-recording-values.png)
+![](/images/instruments-recording-values.png)
 
 If you disable the recording mode on the pattern, it reverts to using the default configuration of the instrument. But the recorded values are still stored, and you can re-enable the recording mode later.
 
@@ -105,4 +105,4 @@ This is a fancy tool which can be very powerful, but it may take some time to ma
 
 ## Adding audio effects
 
-Continue on to [Effects](effects.html), and you will learn about the final piece of the puzzle — global effects and filters.
+Continue on to [Effects](/effects.html), and you will learn about the final piece of the puzzle — global effects and filters.