docs: restructure

demberto · Mar 18, 2023 · f7e1303 · f7e1303
1 parent 71bc48a
commit f7e1303
Show file tree

Hide file tree

Showing 38 changed files with 451 additions and 315 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -17,6 +17,6 @@ sphinx:
 # Optionally declare the Python requirements required to build your docs
 python:
   install:
-    - path: .
+    - path: . # Required by importlib.version for Sphinx (setuptools_scm)
     - requirements: docs/requirements.txt
     - requirements: requirements.txt
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,7 +8,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Unreleased
+## [2.0.0] - 2023-03-18
+
+Welcome PyFLP 2.0 🎉
+Read the previous changelogs to get the complete list of changes.
+
+### Added
+
+- `FruityBloodOverdrive` - thanks to @@ttaschke [#120].
+
+### Changed
+
+- Docs are way more easier to navigate now.
 
 ### Fixed
 
@@ -19,6 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Support for PyPy 3.7 (unable to run tox, cannot find a download).
 
 [#113]: https://github.com/demberto/PyFLP/issues/113
+[#120]: https://github.com/demberto/PyFLP/pull/120
 
 ## [2.0.0a7] - 2022-12-19
 
@@ -629,6 +641,7 @@ Same as in 0.1.1
 - `flpinfo` doesn't output correctly sometimes due to long strings.
 - Extraneous data dumped sometimes by `InsertSlotEvent.Plugin`, why this is caused is not known.
 
+[2.0.0]: https://github.com/demberto/PyFLP/compare/v2.0.0a7.post0...v2.0.0
 [2.0.0a7]: https://github.com/demberto/PyFLP/compare/v2.0.0a6...v2.0.0a7
 [2.0.0a6]: https://github.com/demberto/PyFLP/compare/v2.0.0a5.post...v2.0.0a6
 [2.0.0a5.post]: https://github.com/demberto/PyFLP/compare/v2.0.0a5...v2.0.0a5.post

diff --git a/docs/architecture/flp-format.rst b/docs/architecture/flp-format.rst
@@ -4,7 +4,7 @@ Part I: FLP Format & Events
 FLP is a binary format used by Image-Line FL Studio, a music production
 software, to store project files. Instead of using C-style structs entirely,
 the FLP format has evolved from what once was a MIDI-like format to a really
-bad and messy combination of :wikipedia:`type-length-value` encoded "events"
+bad and messy combination of :wikipedia:`Type-length-value` encoded "events"
 and structs.
 
 Specification

diff --git a/docs/conf.py b/docs/conf.py
@@ -22,16 +22,22 @@
 from pyflp.arrangement import _TrackColorProp
 
 BITLY_LINK = re.compile(r"!\[.*\]\((https://bit\.ly/[A-z0-9]*)\)")
+"""Shortened URLs for links to in-docstring images and docs."""
+
 NEW_IN_FL = re.compile(r"\*New in FL Studio v([^\*]*)\*[\.:](.*)")
+"""Matched in docstrings and replaced with an SVG by :meth:`badge_flstudio`."""
+
 EVENT_ID_DOC = re.compile(r"([0-9\.]*)\+")
 FL_BADGE = "https://img.shields.io/badge/FL%20Studio-{}+-5f686d?labelColor=ff7629&style=for-the-badge"
 GHUC_PREFIX = "https://raw.githubusercontent.com/demberto/PyFLP/master/docs/"
+"""Raw image URL root used for in-docstring images and docs."""
+
 IGNORED_BITLY = ["3RDM1yn"]
 
 project = "PyFLP"
 author = "demberto"
 copyright = f"2022, {author}"
-release = importlib.metadata.version("pyflp")
+release = importlib.metadata.version("pyflp")  # Needs package installation!
 extensions = [
     "hoverxref.extension",
     "m2r2",  # Markdown to reStructuredText conversion
@@ -48,7 +54,7 @@
     "sphinx.ext.todo",  # Items I need to document
     "sphinx.ext.viewcode",  # "Show source" button next to autodoc output
     "sphinx_toolbox",  # Badges and goodies
-    "sphinx_toolbox.github",
+    "sphinx_toolbox.github",  # Link to project issues / PRs easily
     "sphinx_toolbox.more_autodoc.autoprotocol",  # Autodoc extension for typing.Protocol
     "sphinx_toolbox.more_autodoc.sourcelink",  # Python docs-style source code link
     "sphinx_toolbox.sidebar_links",  # Links to repo and PyPi project in the sidebar
@@ -73,9 +79,9 @@
 todo_include_todos = True  # Include .. todo:: directives in output
 todo_emit_warnings = True  # Emit warnings about it as well, so I don't forget
 html_css_files = [
-    "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css"
+    "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.3.0/css/all.min.css"
 ]  # https://sphinx-design.rtfd.io/en/furo-theme/badges_buttons.html#fontawesome-icons
-sd_fontawesome_latex = True
+sd_fontawesome_latex = True  # Output FontAwesome icons in LaTeX
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "construct": ("https://construct.readthedocs.io/en/latest", None),

diff --git a/docs/img/plugin/effects/fruity-blood-overdrive.png b/docs/img/plugin/effects/fruity-blood-overdrive.png
diff --git a/docs/reference.rst b/docs/reference.rst
@@ -7,6 +7,7 @@
    :caption: Contents:
    :glob:
 
+   reference/*/index
    reference/*
 
 :material-outlined:`api` API

diff --git a/docs/reference/arrangement/arrangement.rst b/docs/reference/arrangement/arrangement.rst
@@ -0,0 +1,14 @@
+\ :fas:`trowel-bricks` Arrangement
+==================================
+
+.. currentmodule:: pyflp.arrangement
+
+.. autoclass:: Arrangement
+   :members:
+
+.. autoclass:: TimeSignature
+   :members:
+
+.. autoclass:: ArrangementID
+   :members:
+   :member-order: bysource
diff --git a/docs/reference/arrangement/index.rst b/docs/reference/arrangement/index.rst
@@ -0,0 +1,19 @@
+Arrangements
+============
+
+.. module:: pyflp.arrangement
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+   :caption: Contents:
+   :glob:
+
+   *
+
+.. autoclass:: Arrangements
+   :members:
+
+.. autoclass:: ArrangementsID
+   :members:
+   :member-order: bysource
diff --git a/docs/reference/arrangement/playlist.rst b/docs/reference/arrangement/playlist.rst
@@ -0,0 +1,15 @@
+\ :material-sharp:`playlist_play;1.2em;sd-pb-1` Playlist
+========================================================
+
+.. currentmodule:: pyflp.arrangement
+
+.. autoclass:: PLItemBase
+   :members:
+
+.. autoclass:: ChannelPLItem
+   :members:
+   :show-inheritance: PLItemBase
+
+.. autoclass:: PatternPLItem
+   :members:
+   :show-inheritance: PLItemBase
diff --git a/docs/reference/arrangements.rst → docs/reference/arrangement/track.rst b/docs/reference/arrangements.rst → docs/reference/arrangement/track.rst
@@ -1,30 +1,7 @@
-Arrangements
-============
-
-.. module:: pyflp.arrangement
-.. autoclass:: Arrangements
-   :members:
-
-Arrangement
------------
-
-.. autoclass:: Arrangement
-   :members:
-
-Playlist
---------
-
-.. autoclass:: PLItemBase
-   :members:
-.. autoclass:: ChannelPLItem
-   :members:
-   :show-inheritance: PLItemBase
-.. autoclass:: PatternPLItem
-   :members:
-   :show-inheritance: PLItemBase
-
 Track
------
+=====
+
+.. currentmodule:: pyflp.arrangement
 
 .. autoclass:: Track
    :members:
@@ -68,21 +45,6 @@ Track
 
       .. image:: /img/arrangement/track/sync.png
 
-Classes
--------
-
-.. autoclass:: TimeSignature
-   :members:
-
-Event IDs
----------
-
-.. autoclass:: ArrangementsID
-   :members:
-   :member-order: bysource
-.. autoclass:: ArrangementID
-   :members:
-   :member-order: bysource
 .. autoclass:: TrackID
    :members:
    :member-order: bysource
diff --git a/docs/reference/channel/automation.rst b/docs/reference/channel/automation.rst
@@ -0,0 +1,13 @@
+\ :fas:`bezier-curve` Automation
+================================
+
+.. currentmodule:: pyflp.channel
+
+.. autoclass:: Automation
+   :members:
+
+.. autoclass:: AutomationLFO
+   :members:
+
+.. autoclass:: AutomationPoint
+   :members:
diff --git a/docs/reference/channel/channel.rst b/docs/reference/channel/channel.rst
@@ -0,0 +1,17 @@
+Channel
+=======
+
+.. currentmodule:: pyflp.channel
+
+.. autoclass:: Channel
+   :members:
+
+Enums
+-----
+
+.. autoclass:: ChannelType
+   :members:
+
+.. autoclass:: ChannelID
+   :members:
+   :member-order: bysource
diff --git a/docs/reference/channel/display-group.rst b/docs/reference/channel/display-group.rst
@@ -0,0 +1,11 @@
+DisplayGroup
+============
+
+.. currentmodule:: pyflp.channel
+
+.. autoclass:: DisplayGroup
+   :members:
+
+.. autoclass:: DisplayGroupID
+   :members:
+   :member-order: bysource
diff --git a/docs/reference/channel/index.rst b/docs/reference/channel/index.rst
@@ -0,0 +1,20 @@
+\ :material-sharp:`dns;1.2em;sd-pb-1` Channel Rack
+==================================================
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+   :caption: Contents:
+   :glob:
+
+   *
+
+.. module:: pyflp.channel
+.. autoclass:: ChannelRack
+   :members:
+
+.. autoclass:: RackID
+   :members:
+   :member-order: bysource
+
+.. autoexception:: ChannelNotFound
diff --git a/docs/reference/channel/instrument.rst b/docs/reference/channel/instrument.rst
@@ -0,0 +1,7 @@
+Instrument
+==========
+
+.. currentmodule:: pyflp.channel
+
+.. autoclass:: Instrument
+   :members:
diff --git a/docs/reference/channel/layer.rst b/docs/reference/channel/layer.rst
@@ -0,0 +1,7 @@
+\ :fas:`layer-group` Layer
+==========================
+
+.. currentmodule:: pyflp.channel
+
+.. autoclass:: Layer
+   :members:
diff --git a/docs/reference/channel/sampler.rst b/docs/reference/channel/sampler.rst
@@ -0,0 +1,56 @@
+\ :material-sharp:`audio_file;1.2em;sd-pb-1` Sampler
+====================================================
+
+.. currentmodule:: pyflp.channel
+
+.. autoclass:: Sampler
+   :members:
+
+.. autoclass:: Content
+   :members:
+
+.. autoclass:: Envelope
+   :members:
+
+.. autoclass:: Filter
+   :members:
+
+.. autoclass:: FX
+   :members:
+
+.. autoclass:: Playback
+   :members:
+
+.. autoclass:: Reverb
+   :members:
+
+.. autoclass:: SamplerLFO
+   :members:
+
+.. autoclass:: TimeStretching
+   :members:
+
+Enums
+-----
+
+.. autoclass:: DeclickMode
+   :members:
+
+.. autoclass:: LFOShape
+   :members:
+
+.. autoclass:: ReverbType
+   :members:
+
+.. grid::
+
+   .. grid-item::
+
+      .. autoclass:: StretchMode
+         :members:
+
+   .. grid-item::
+      :child-align: center
+      :columns: auto
+
+      .. image:: /img/channel/stretch-mode.png
diff --git a/docs/reference/channel/shared.rst b/docs/reference/channel/shared.rst
@@ -0,0 +1,33 @@
+Shared
+======
+
+.. currentmodule:: pyflp.channel
+
+These implement functionality used by :class:`Channel` or its subclasses.
+
+.. autoclass:: Arp
+   :members:
+
+.. autoclass:: Delay
+   :members:
+
+.. autoclass:: Keyboard
+   :members:
+
+.. autoclass:: LevelAdjusts
+   :members:
+
+.. autoclass:: Polyphony
+   :members:
+
+.. autoclass:: Time
+   :members:
+
+.. autoclass:: Tracking
+   :members:
+
+Enums
+-----
+
+.. autoclass:: ArpDirection
+   :members: