diff --git a/Tools/DocumentationCLI/.gitignore b/Tools/DocumentationCLI/.gitignore new file mode 100644 index 000000000..ec376bb82 --- /dev/null +++ b/Tools/DocumentationCLI/.gitignore @@ -0,0 +1,2 @@ +.idea +target \ No newline at end of file diff --git a/Tools/DocumentationCLI/Cargo.lock b/Tools/DocumentationCLI/Cargo.lock new file mode 100644 index 000000000..f437a6c51 --- /dev/null +++ b/Tools/DocumentationCLI/Cargo.lock @@ -0,0 +1,643 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 3 + +[[package]] +name = "FicsItNetworksDocumentationCLI" +version = "0.1.0" +dependencies = [ + "getopts", + "indoc", + "regex", + "serde", + "serde_json", + "serde_with", + "toml", +] + +[[package]] +name = "aho-corasick" +version = "1.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e60d3430d3a69478ad0993f19238d2df97c507009a52b3c10addcd7f6bcb916" +dependencies = [ + "memchr", +] + +[[package]] +name = "android-tzdata" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e999941b234f3131b00bc13c22d06e8c5ff726d1b6318ac7eb276997bbb4fef0" + +[[package]] +name = "android_system_properties" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "819e7219dbd41043ac279b19830f2efc897156490d7fd6ea916720117ee66311" +dependencies = [ + "libc", +] + +[[package]] +name = "autocfg" +version = "1.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c4b4d0bd25bd0b74681c0ad21497610ce1b7c91b1022cd21c80c6fbdd9476b0" + +[[package]] +name = "base64" +version = "0.22.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6" + +[[package]] +name = "bumpalo" +version = "3.16.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "79296716171880943b8470b5f8d03aa55eb2e645a4874bdbb28adb49162e012c" + +[[package]] +name = "cc" +version = "1.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2aba8f4e9906c7ce3c73463f62a7f0c65183ada1a2d47e397cc8810827f9694f" + +[[package]] +name = "cfg-if" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd" + +[[package]] +name = "chrono" +version = "0.4.38" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a21f936df1771bf62b77f047b726c4625ff2e8aa607c01ec06e5a05bd8463401" +dependencies = [ + "android-tzdata", + "iana-time-zone", + "num-traits", + "serde", + "windows-targets", +] + +[[package]] +name = "core-foundation-sys" +version = "0.8.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "06ea2b9bc92be3c2baa9334a323ebca2d6f074ff852cd1d7b11064035cd3868f" + +[[package]] +name = "darling" +version = "0.20.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6f63b86c8a8826a49b8c21f08a2d07338eec8d900540f8630dc76284be802989" +dependencies = [ + "darling_core", + "darling_macro", +] + +[[package]] +name = "darling_core" +version = "0.20.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "95133861a8032aaea082871032f5815eb9e98cef03fa916ab4500513994df9e5" +dependencies = [ + "fnv", + "ident_case", + "proc-macro2", + "quote", + "strsim", + "syn", +] + +[[package]] +name = "darling_macro" +version = "0.20.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d336a2a514f6ccccaa3e09b02d41d35330c07ddf03a62165fcec10bb561c7806" +dependencies = [ + "darling_core", + "quote", + "syn", +] + +[[package]] +name = "deranged" +version = "0.3.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b42b6fa04a440b495c8b04d0e71b707c585f83cb9cb28cf8cd0d976c315e31b4" +dependencies = [ + "powerfmt", + "serde", +] + +[[package]] +name = "equivalent" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5443807d6dff69373d433ab9ef5378ad8df50ca6298caf15de6e52e24aaf54d5" + +[[package]] +name = "fnv" +version = "1.0.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1" + +[[package]] +name = "getopts" +version = "0.2.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "14dbbfd5c71d70241ecf9e6f13737f7b5ce823821063188d7e46c41d371eebd5" +dependencies = [ + "unicode-width", +] + +[[package]] +name = "hashbrown" +version = "0.12.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8a9ee70c43aaf417c914396645a0fa852624801b24ebb7ae78fe8272889ac888" + +[[package]] +name = "hashbrown" +version = "0.14.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1" + +[[package]] +name = "hex" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70" + +[[package]] +name = "iana-time-zone" +version = "0.1.60" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7ffbb5a1b541ea2561f8c41c087286cc091e21e556a4f09a8f6cbf17b69b141" +dependencies = [ + "android_system_properties", + "core-foundation-sys", + "iana-time-zone-haiku", + "js-sys", + "wasm-bindgen", + "windows-core", +] + +[[package]] +name = "iana-time-zone-haiku" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f" +dependencies = [ + "cc", +] + +[[package]] +name = "ident_case" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b9e0384b61958566e926dc50660321d12159025e767c18e043daf26b70104c39" + +[[package]] +name = "indexmap" +version = "1.9.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bd070e393353796e801d209ad339e89596eb4c8d430d18ede6a1cced8fafbd99" +dependencies = [ + "autocfg", + "hashbrown 0.12.3", + "serde", +] + +[[package]] +name = "indexmap" +version = "2.2.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "168fb715dda47215e360912c096649d23d58bf392ac62f73919e831745e40f26" +dependencies = [ + "equivalent", + "hashbrown 0.14.5", + "serde", +] + +[[package]] +name = "indoc" +version = "2.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b248f5224d1d606005e02c97f5aa4e88eeb230488bcc03bc9ca4d7991399f2b5" + +[[package]] +name = "itoa" +version = "1.0.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "49f1f14873335454500d59611f1cf4a4b0f786f9ac11f4312a78e4cf2566695b" + +[[package]] +name = "js-sys" +version = "0.3.69" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29c15563dc2726973df627357ce0c9ddddbea194836909d655df6a75d2cf296d" +dependencies = [ + "wasm-bindgen", +] + +[[package]] +name = "libc" +version = "0.2.155" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "97b3888a4aecf77e811145cadf6eef5901f4782c53886191b2f693f24761847c" + +[[package]] +name = "log" +version = "0.4.22" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a7a70ba024b9dc04c27ea2f0c0548feb474ec5c54bba33a7f72f873a39d07b24" + +[[package]] +name = "memchr" +version = "2.7.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78ca9ab1a0babb1e7d5695e3530886289c18cf2f87ec19a575a0abdce112e3a3" + +[[package]] +name = "num-conv" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "51d515d32fb182ee37cda2ccdcb92950d6a3c2893aa280e540671c2cd0f3b1d9" + +[[package]] +name = "num-traits" +version = "0.2.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841" +dependencies = [ + "autocfg", +] + +[[package]] +name = "once_cell" +version = "1.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3fdb12b2476b595f9358c5161aa467c2438859caa136dec86c26fdd2efe17b92" + +[[package]] +name = "powerfmt" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "439ee305def115ba05938db6eb1644ff94165c5ab5e9420d1c1bcedbba909391" + +[[package]] +name = "proc-macro2" +version = "1.0.86" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5e719e8df665df0d1c8fbfd238015744736151d4445ec0836b8e628aae103b77" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.36" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0fa76aaf39101c457836aec0ce2316dbdc3ab723cdda1c6bd4e6ad4208acaca7" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "regex" +version = "1.10.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b91213439dad192326a0d7c6ee3955910425f441d7038e0d6933b0aec5c4517f" +dependencies = [ + "aho-corasick", + "memchr", + "regex-automata", + "regex-syntax", +] + +[[package]] +name = "regex-automata" +version = "0.4.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "38caf58cc5ef2fed281f89292ef23f6365465ed9a41b7a7754eb4e26496c92df" +dependencies = [ + "aho-corasick", + "memchr", + "regex-syntax", +] + +[[package]] +name = "regex-syntax" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7a66a03ae7c801facd77a29370b4faec201768915ac14a721ba36f20bc9c209b" + +[[package]] +name = "ryu" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f3cb5ba0dc43242ce17de99c180e96db90b235b8a9fdc9543c96d2209116bd9f" + +[[package]] +name = "serde" +version = "1.0.204" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bc76f558e0cbb2a839d37354c575f1dc3fdc6546b5be373ba43d95f231bf7c12" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.204" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e0cd7e117be63d3c3678776753929474f3b04a43a080c744d6b0ae2a8c28e222" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "serde_json" +version = "1.0.120" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e0d21c9a8cae1235ad58a00c11cb40d4b1e5c784f1ef2c537876ed6ffd8b7c5" +dependencies = [ + "itoa", + "ryu", + "serde", +] + +[[package]] +name = "serde_spanned" +version = "0.6.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "eb5b1b31579f3811bf615c144393417496f152e12ac8b7663bf664f4a815306d" +dependencies = [ + "serde", +] + +[[package]] +name = "serde_with" +version = "3.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69cecfa94848272156ea67b2b1a53f20fc7bc638c4a46d2f8abde08f05f4b857" +dependencies = [ + "base64", + "chrono", + "hex", + "indexmap 1.9.3", + "indexmap 2.2.6", + "serde", + "serde_derive", + "serde_json", + "serde_with_macros", + "time", +] + +[[package]] +name = "serde_with_macros" +version = "3.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a8fee4991ef4f274617a51ad4af30519438dacb2f56ac773b08a1922ff743350" +dependencies = [ + "darling", + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "strsim" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" + +[[package]] +name = "syn" +version = "2.0.72" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc4b9b9bf2add8093d3f2c0204471e951b2285580335de42f9d2534f3ae7a8af" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "time" +version = "0.3.36" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5dfd88e563464686c916c7e46e623e520ddc6d79fa6641390f2e3fa86e83e885" +dependencies = [ + "deranged", + "itoa", + "num-conv", + "powerfmt", + "serde", + "time-core", + "time-macros", +] + +[[package]] +name = "time-core" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ef927ca75afb808a4d64dd374f00a2adf8d0fcff8e7b184af886c3c87ec4a3f3" + +[[package]] +name = "time-macros" +version = "0.2.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f252a68540fde3a3877aeea552b832b40ab9a69e318efd078774a01ddee1ccf" +dependencies = [ + "num-conv", + "time-core", +] + +[[package]] +name = "toml" +version = "0.8.16" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "81967dd0dd2c1ab0bc3468bd7caecc32b8a4aa47d0c8c695d8c2b2108168d62c" +dependencies = [ + "serde", + "serde_spanned", + "toml_datetime", + "toml_edit", +] + +[[package]] +name = "toml_datetime" +version = "0.6.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8fb9f64314842840f1d940ac544da178732128f1c78c21772e876579e0da1db" +dependencies = [ + "serde", +] + +[[package]] +name = "toml_edit" +version = "0.22.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8d9f8729f5aea9562aac1cc0441f5d6de3cff1ee0c5d67293eeca5eb36ee7c16" +dependencies = [ + "indexmap 2.2.6", + "serde", + "serde_spanned", + "toml_datetime", + "winnow", +] + +[[package]] +name = "unicode-ident" +version = "1.0.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3354b9ac3fae1ff6755cb6db53683adb661634f67557942dea4facebec0fee4b" + +[[package]] +name = "unicode-width" +version = "0.1.13" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0336d538f7abc86d282a4189614dfaa90810dfc2c6f6427eaf88e16311dd225d" + +[[package]] +name = "wasm-bindgen" +version = "0.2.92" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4be2531df63900aeb2bca0daaaddec08491ee64ceecbee5076636a3b026795a8" +dependencies = [ + "cfg-if", + "wasm-bindgen-macro", +] + +[[package]] +name = "wasm-bindgen-backend" +version = "0.2.92" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "614d787b966d3989fa7bb98a654e369c762374fd3213d212cfc0251257e747da" +dependencies = [ + "bumpalo", + "log", + "once_cell", + "proc-macro2", + "quote", + "syn", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-macro" +version = "0.2.92" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a1f8823de937b71b9460c0c34e25f3da88250760bec0ebac694b49997550d726" +dependencies = [ + "quote", + "wasm-bindgen-macro-support", +] + +[[package]] +name = "wasm-bindgen-macro-support" +version = "0.2.92" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e94f17b526d0a461a191c78ea52bbce64071ed5c04c9ffe424dcb38f74171bb7" +dependencies = [ + "proc-macro2", + "quote", + "syn", + "wasm-bindgen-backend", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-shared" +version = "0.2.92" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "af190c94f2773fdb3729c55b007a722abb5384da03bc0986df4c289bf5567e96" + +[[package]] +name = "windows-core" +version = "0.52.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "33ab640c8d7e35bf8ba19b884ba838ceb4fba93a4e8c65a9059d08afcfc683d9" +dependencies = [ + "windows-targets", +] + +[[package]] +name = "windows-targets" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973" +dependencies = [ + "windows_aarch64_gnullvm", + "windows_aarch64_msvc", + "windows_i686_gnu", + "windows_i686_gnullvm", + "windows_i686_msvc", + "windows_x86_64_gnu", + "windows_x86_64_gnullvm", + "windows_x86_64_msvc", +] + +[[package]] +name = "windows_aarch64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3" + +[[package]] +name = "windows_aarch64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469" + +[[package]] +name = "windows_i686_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b" + +[[package]] +name = "windows_i686_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66" + +[[package]] +name = "windows_i686_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66" + +[[package]] +name = "windows_x86_64_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78" + +[[package]] +name = "windows_x86_64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d" + +[[package]] +name = "windows_x86_64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" + +[[package]] +name = "winnow" +version = "0.6.16" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b480ae9340fc261e6be3e95a1ba86d54ae3f9171132a73ce8d4bbaf68339507c" +dependencies = [ + "memchr", +] diff --git a/Tools/DocumentationCLI/Cargo.toml b/Tools/DocumentationCLI/Cargo.toml new file mode 100644 index 000000000..b23197ff6 --- /dev/null +++ b/Tools/DocumentationCLI/Cargo.toml @@ -0,0 +1,13 @@ +[package] +name = "FicsItNetworksDocumentationCLI" +version = "0.1.0" +edition = "2021" + +[dependencies] +getopts = "0.2.21" +serde = { version = "1.0.204", features = ["derive"] } +serde_with = "3.9.0" +serde_json = "1.0.120" +regex = "1.10.5" +indoc = "2.0.5" +toml = "0.8.16" \ No newline at end of file diff --git a/Tools/DocumentationCLI/rustfmt.toml b/Tools/DocumentationCLI/rustfmt.toml new file mode 100644 index 000000000..218e20321 --- /dev/null +++ b/Tools/DocumentationCLI/rustfmt.toml @@ -0,0 +1 @@ +hard_tabs = true diff --git a/Tools/DocumentationCLI/src/config.rs b/Tools/DocumentationCLI/src/config.rs new file mode 100644 index 000000000..642600a30 --- /dev/null +++ b/Tools/DocumentationCLI/src/config.rs @@ -0,0 +1,36 @@ +use serde::Deserialize; +use std::path::{Path, PathBuf}; + +#[derive(Deserialize, Debug)] +pub struct Config { + pub nav_file_path: PathBuf, + pub reflection_folder: PathBuf, + pub lua_folder: PathBuf, + #[serde(skip)] + pub config_path: PathBuf, +} + +impl Config { + pub fn load(config_path: &Path) -> std::io::Result { + let contents = std::fs::read_to_string(config_path)?; + let mut config: Config = toml::from_str(&contents) + .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?; + config.config_path = std::path::absolute(config_path).unwrap(); + Ok(config) + } + + pub fn abs_nav_file_path(&self) -> PathBuf { + self.config_path.parent().unwrap().join(&self.nav_file_path) + } + + pub fn abs_reflection_path(&self) -> PathBuf { + self.config_path + .parent() + .unwrap() + .join(&self.reflection_folder) + } + + pub fn abs_lua_path(&self) -> PathBuf { + self.config_path.parent().unwrap().join(&self.lua_folder) + } +} diff --git a/Tools/DocumentationCLI/src/context.rs b/Tools/DocumentationCLI/src/context.rs new file mode 100644 index 000000000..5d46af4d6 --- /dev/null +++ b/Tools/DocumentationCLI/src/context.rs @@ -0,0 +1,224 @@ +use crate::config::Config; +use crate::documentation::Documentation; +use crate::util::path_to_forward_slash; +use std::borrow::Borrow; +use std::collections::{HashMap, HashSet}; +use std::path::PathBuf; + +pub struct Context { + pub config: Config, + pub abs_classes_path: PathBuf, + pub classes: HashSet, + pub class_pages: HashMap, + pub abs_structs_path: PathBuf, + pub class_redirects: HashMap, + pub structs: HashSet, + pub struct_pages: HashMap, + pub struct_redirects: HashMap, + pub abs_lua_path: PathBuf, + pub lua_pages: HashMap, + pub lua_types: HashSet, + pub lua_type_pages: HashMap, +} + +impl Context { + pub fn new(config: Config, documentation: &Documentation) -> Self { + let abs_pages_path = config.abs_nav_file_path().parent().unwrap().join("pages"); + let abs_classes_path = config + .config_path + .parent() + .unwrap() + .join(&config.reflection_folder) + .join("classes"); + let abs_structs_path = config + .config_path + .parent() + .unwrap() + .join(&config.reflection_folder) + .join("classes"); + let abs_lua_path = config + .config_path + .parent() + .unwrap() + .join(&config.lua_folder); + let classes_path = abs_classes_path.strip_prefix(&abs_pages_path).unwrap(); + let structs_path = abs_structs_path.strip_prefix(&abs_pages_path).unwrap(); + let lua_path = abs_lua_path.strip_prefix(&abs_pages_path).unwrap(); + + let classes: HashSet<_> = documentation + .reflection + .classes + .iter() + .map(|c| c.reflection_struct.base.internal_name.clone()) + .collect(); + let structs: HashSet<_> = documentation + .reflection + .structs + .iter() + .map(|s| s.base.internal_name.clone()) + .collect(); + let lua_types: HashSet<_> = documentation + .lua + .modules + .iter() + .map(|m| &m.metatables) + .flatten() + .map(|m| m.base.internal_name.clone()) + .collect(); + + let (class_redirects, class_pages): (Vec<_>, Vec<_>) = + documentation.reflection.classes.iter().partition(|c| { + c.reflection_struct.properties.is_empty() + && c.reflection_struct.functions.is_empty() + && c.signals.is_empty() + && c.reflection_struct.parent.is_some() + }); + let class_redirects = class_redirects + .into_iter() + .map(|c| { + ( + c.reflection_struct.base.internal_name.clone(), + c.reflection_struct.parent.clone().unwrap(), + ) + }) + .collect(); + let class_pages = class_pages + .into_iter() + .map(|c| &c.reflection_struct.base.internal_name) + .map(|s| { + ( + s.clone(), + path_to_forward_slash(&classes_path.join(format!("{s}.adoc"))).unwrap(), + ) + }) + .collect(); + + let (struct_redirects, struct_pages): (Vec<_>, Vec<_>) = + documentation.reflection.structs.iter().partition(|s| { + s.properties.is_empty() && s.functions.is_empty() && s.parent.is_some() + }); + let struct_redirects = struct_redirects + .into_iter() + .map(|s| (s.base.internal_name.clone(), s.parent.clone().unwrap())) + .collect(); + let struct_pages = struct_pages + .into_iter() + .map(|s| &s.base.internal_name) + .map(|s| { + ( + s.clone(), + path_to_forward_slash(&structs_path.join(format!("{s}.adoc"))).unwrap(), + ) + }) + .collect(); + + let lua_pages = documentation + .lua + .modules + .iter() + .map(|m| &m.base.internal_name) + .map(|s| { + ( + s.clone(), + path_to_forward_slash(&lua_path.join(format!("{s}.adoc"))).unwrap(), + ) + }) + .collect(); + let lua_type_pages = documentation + .lua + .modules + .iter() + .map(|m| { + m.metatables.iter().map(|t| { + ( + t.base.internal_name.clone(), + path_to_forward_slash(&lua_path.join(format!( + "{}.adoc#_{}", + m.base.internal_name, + t.base.internal_name.to_lowercase() + ))) + .unwrap(), + ) + }) + }) + .flatten() + .collect(); + + Self { + config, + abs_classes_path, + classes, + class_pages, + abs_structs_path, + structs, + struct_pages, + abs_lua_path, + lua_pages, + lua_types, + lua_type_pages, + class_redirects, + struct_redirects, + } + } + + pub fn abs_class_path(&self, class: &str) -> PathBuf { + self.abs_classes_path.join(format!("{class}.adoc")) + } + + pub fn abs_struct_path(&self, struct_name: &str) -> PathBuf { + self.abs_structs_path.join(format!("{struct_name}.adoc")) + } + + pub fn abs_lua_module_path(&self, module: &str) -> PathBuf { + self.abs_lua_path.join(format!("{module}.adoc")) + } + + pub fn xref_class>(&self, class: &Option) -> String { + let class = class.as_ref().map(|s| s.borrow()).unwrap_or("Object"); + let mut parent = class; + while let Some(redirected) = self.class_redirects.get(parent) { + parent = redirected; + } + if let Some(path) = self.class_pages.get(parent) { + format!("xref:/{path}[{class}]") + } else { + class.to_string() + } + } + + pub fn xref_struct>(&self, struct_type: &Option) -> String { + let struct_type = struct_type + .as_ref() + .map(|s| { + let mut struct_type = s.borrow(); + while let Some(redirected) = self.struct_redirects.get(struct_type) { + struct_type = redirected; + } + self.struct_pages.get(struct_type).map(|p| (s.borrow(), p)) + }) + .flatten(); + if let Some((struct_type, path)) = struct_type { + format!("xref:/{path}[{struct_type}]") + } else { + "any".to_string() + } + } + + pub fn xref_lua_module>(&self, lua_module: S) -> String { + let lua_module = lua_module.borrow(); + if let Some(path) = self.lua_pages.get(lua_module) { + format!("xref:/{path}[{lua_module}]") + } else { + lua_module.to_string() + } + } + + pub fn xref_lua_type>(&self, lua_type: S) -> String { + let lua_type = lua_type.borrow(); + if let Some(path) = self.lua_type_pages.get(lua_type) { + format!("xref:/{path}[{lua_type}]") + } else { + lua_type.to_string() + } + } +} diff --git a/Tools/DocumentationCLI/src/documentation.rs b/Tools/DocumentationCLI/src/documentation.rs new file mode 100644 index 000000000..03ad51275 --- /dev/null +++ b/Tools/DocumentationCLI/src/documentation.rs @@ -0,0 +1,22 @@ +use crate::lua::LuaDocumentation; +use crate::reflection::ReflectionDocumentation; +use serde::Deserialize; +use std::io::BufReader; +use std::path::Path; + +#[derive(Deserialize, Debug)] +pub struct Documentation { + pub reflection: ReflectionDocumentation, + pub lua: LuaDocumentation, +} + +impl Documentation { + pub fn load(path: &Path) -> std::io::Result { + let file = std::fs::File::open(path) + .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?; + let buf = BufReader::new(file); + let documentation: Self = serde_json::from_reader(buf) + .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?; + Ok(documentation) + } +} diff --git a/Tools/DocumentationCLI/src/lua.rs b/Tools/DocumentationCLI/src/lua.rs new file mode 100644 index 000000000..56c473a26 --- /dev/null +++ b/Tools/DocumentationCLI/src/lua.rs @@ -0,0 +1,300 @@ +use crate::context::Context; +use crate::util::prefix_string_lines; +use regex::{Captures, Regex}; +use serde::Deserialize; +use serde_with::{serde_as, KeyValueMap}; +use std::fs::File; +use std::io::{Result, Write}; + +#[derive(Deserialize, Debug)] +pub struct LuaBase { + #[serde(rename = "$key$")] + pub internal_name: String, + #[serde(alias = "displayName")] + pub display_name: Option, + pub description: String, +} + +impl LuaBase { + pub fn display_name(&self) -> &str { + self.display_name.as_deref().unwrap_or(&self.internal_name) + } + + pub fn name_adoc(&self) -> String { + if let Some(display_name) = &self.display_name { + format!("*{display_name}* `{}`", self.internal_name) + } else { + format!("`{}`", self.internal_name) + } + } +} + +#[derive(Deserialize, Debug)] +pub struct LuaTableField { + #[serde(flatten)] + pub base: LuaBase, + #[serde(flatten)] + pub value: LuaValue, +} + +#[derive(Deserialize, Debug)] +pub struct LuaFunctionParameter { + #[serde(flatten)] + pub base: LuaBase, + #[serde(alias = "type")] + pub lua_type: String, +} + +#[serde_as] +#[derive(Deserialize, Debug)] +#[serde(tag = "valueType")] +pub enum LuaValue { + #[serde(alias = "table")] + Table { + #[serde_as(as = "KeyValueMap<_>")] + fields: Vec, + }, + #[serde(alias = "function")] + Function { + #[serde(alias = "parameterSignature")] + parameter_signature: String, + #[serde(alias = "returnValueSignature")] + return_value_signature: String, + #[serde_as(as = "KeyValueMap<_>")] + parameters: Vec, + #[serde(alias = "returnValues")] + #[serde_as(as = "KeyValueMap<_>")] + return_values: Vec, + }, + #[serde(alias = "bareValue")] + BareValue { + #[serde(alias = "luaType")] + lua_type: String, + }, +} + +#[derive(Deserialize, Debug)] +pub struct LuaMetatable { + #[serde(flatten)] + pub base: LuaBase, + #[serde(flatten)] + pub table: LuaValue, +} + +#[derive(Deserialize, Debug)] +pub struct LuaGlobal { + #[serde(flatten)] + pub base: LuaBase, + #[serde(flatten)] + pub value: LuaValue, +} + +#[serde_as] +#[derive(Deserialize, Debug)] +pub struct LuaModule { + #[serde(flatten)] + pub base: LuaBase, + pub dependencies: Vec, + #[serde_as(as = "KeyValueMap<_>")] + pub metatables: Vec, + #[serde_as(as = "KeyValueMap<_>")] + pub globals: Vec, +} + +#[serde_as] +#[derive(Deserialize, Debug)] +pub struct LuaDocumentation { + #[serde_as(as = "KeyValueMap<_>")] + pub modules: Vec, +} + +pub struct LuaContext<'a> { + pub ctx: &'a Context, +} + +impl<'a> LuaContext<'a> { + pub fn new(context: &'a Context) -> Self { + Self { ctx: context } + } + + fn lua_type_identifier_adoc(&self, identifier: &str) -> String { + if self.ctx.classes.contains(identifier) { + self.ctx.xref_class(&Some(identifier)) + } else if self.ctx.structs.contains(identifier) { + self.ctx.xref_struct(&Some(identifier)) + } else if self.ctx.lua_types.contains(identifier) { + self.ctx.xref_lua_type(identifier) + } else { + identifier.to_string() + } + } + + fn patch_lua_types(&self, str: &str) -> String { + let regex = Regex::new(r"[\w\-]+").unwrap(); + regex + .replace_all(str, |captures: &Captures| -> String { + let str = captures.get(0).unwrap().as_str(); + self.lua_type_identifier_adoc(str) + }) + .to_string() + } + + fn write_function_parameter_table<'b, I: Iterator>( + &self, + file: &mut File, + parameters: I, + ) -> Result<()> { + writeln!(file, r#"[%header,cols="1,1,4a"]"#)?; + writeln!(file, r#"|==="#)?; + writeln!(file, r#"|Name |Type |Description"#)?; + writeln!(file)?; + + for parameter in parameters { + writeln!(file, "| {}", parameter.base.name_adoc())?; + writeln!(file, "| {}", self.patch_lua_types(¶meter.lua_type))?; + writeln!( + file, + "| {}", + prefix_string_lines(" ", ¶meter.base.description) + )?; + writeln!(file)?; + } + + writeln!(file, r#"|==="#)?; + + Ok(()) + } + + fn write_value( + &self, + file: &mut File, + header: &str, + identifier: &str, + base: &LuaBase, + value: &LuaValue, + ) -> Result<()> { + if base.internal_name.starts_with("__") { + return Ok(()); + } + + let suffix = match value { + LuaValue::Table { .. } => "".to_string(), + LuaValue::Function { + parameter_signature, + return_value_signature, + parameters: _, + return_values: _, + } => { + let parameters = self.patch_lua_types(¶meter_signature); + if return_value_signature.is_empty() { + format!(" ({parameters})") + } else { + let return_values = self.patch_lua_types(&return_value_signature); + format!(" ({parameters}) -> {return_values}") + } + } + LuaValue::BareValue { lua_type } => format!(" : {}", self.patch_lua_types(lua_type)), + }; + + let identifier = if identifier.is_empty() { + identifier.to_string() + } else { + format!("{identifier}.") + }; + + let header_identifier = if identifier.is_empty() { + "".to_string() + } else { + format!("__{identifier}__") + }; + + writeln!( + file, + "{header} {header_identifier}**{}**{suffix}", + base.internal_name + )?; + writeln!(file, "{}", base.description)?; + writeln!(file)?; + + let header = format!("{header}="); + let identifier = format!("{identifier}{}", base.internal_name); + + match value { + LuaValue::Table { fields } => { + for field in fields { + self.write_value(file, &header, &identifier, &field.base, &field.value)?; + } + } + LuaValue::Function { + parameters, + return_values, + parameter_signature: _, + return_value_signature: _, + } => { + if !parameters.is_empty() { + writeln!(file, "Parameters::")?; + self.write_function_parameter_table(file, parameters.iter())?; + writeln!(file)?; + } + if !return_values.is_empty() { + writeln!(file, "Return Values::")?; + self.write_function_parameter_table(file, return_values.iter())?; + writeln!(file)?; + } + } + _ => {} + } + + Ok(()) + } + + fn write_global(&self, file: &mut File, global: &LuaGlobal) -> Result<()> { + self.write_value(file, "===", "", &global.base, &global.value) + } + + fn write_metatable(&self, file: &mut File, metatable: &LuaMetatable) -> Result<()> { + self.write_value(file, "===", "", &metatable.base, &metatable.table) + } + + pub fn write_module(&self, file: &mut File, module: &LuaModule) -> Result<()> { + writeln!(file, "= {}", module.base.display_name())?; + writeln!(file, "{}", module.base.description)?; + writeln!(file)?; + + if !module.dependencies.is_empty() { + let dependencies: String = module + .dependencies + .iter() + .map(|s| self.ctx.xref_lua_module(s.as_str())) + .intersperse(", ".to_string()) + .collect(); + + writeln!(file, r#"[cols="1,5a"]"#)?; + writeln!(file, "|===")?; + writeln!(file, "|Dependencies")?; + writeln!(file, "| {dependencies}")?; + writeln!(file, "|===")?; + writeln!(file)?; + } + + if !module.globals.is_empty() { + writeln!(file, "== Globals")?; + writeln!(file)?; + + for global in &module.globals { + self.write_global(file, global)?; + } + } + + if !module.metatables.is_empty() { + writeln!(file, "== Types")?; + writeln!(file)?; + + for metatable in &module.metatables { + self.write_metatable(file, metatable)?; + } + } + + Ok(()) + } +} diff --git a/Tools/DocumentationCLI/src/main.rs b/Tools/DocumentationCLI/src/main.rs new file mode 100644 index 000000000..9042665fb --- /dev/null +++ b/Tools/DocumentationCLI/src/main.rs @@ -0,0 +1,211 @@ +#![feature(iter_intersperse)] + +mod config; +mod context; +mod documentation; +mod lua; +mod reflection; +mod util; + +use crate::config::Config; +use crate::context::Context; +use crate::documentation::Documentation; +use crate::lua::{LuaContext, LuaDocumentation}; +use crate::reflection::{ReflectionContext, ReflectionDocumentation}; +use regex::Regex; +use std::fs::{create_dir_all, remove_dir_all, File}; +use std::io::Write; +use std::io::{BufRead, BufReader}; +use std::path::{Path, PathBuf}; + +fn fatal(error: &str) -> T { + eprintln!("Fatal error occurred: {}", error); + std::process::exit(-1) +} + +fn remove_files_in_folder(path: &Path) { + let _ = remove_dir_all(path); + create_dir_all(path).unwrap_or_else(|e| { + fatal(&format!( + "Unable to create empty folder '{}': {e}", + path.to_str().unwrap_or("") + )) + }); +} + +fn write_reflection_files(context: &Context, doc: &ReflectionDocumentation) { + remove_files_in_folder(&context.config.abs_reflection_path()); + + let classes = doc.classes.iter().filter(|c| { + context + .class_pages + .contains_key(&c.reflection_struct.base.internal_name) + }); + let structs = doc + .structs + .iter() + .filter(|s| context.struct_pages.contains_key(&s.base.internal_name)); + + let context = ReflectionContext::new(context); + + create_dir_all(&context.ctx.abs_classes_path) + .unwrap_or_else(|e| fatal(&format!("Unable to create structs folder: {e}"))); + for ref_class in classes { + let path = context + .ctx + .abs_class_path(&ref_class.reflection_struct.base.internal_name); + let mut file = File::create(&path).unwrap_or_else(|e| { + fatal(&format!( + "Failed to create class file '{}': {e}", + path.to_str().unwrap_or("") + )) + }); + context.write_class(&mut file, &ref_class).unwrap(); + } + + create_dir_all(&context.ctx.abs_structs_path) + .unwrap_or_else(|e| fatal(&format!("Unable to create structs folder: {e}"))); + for ref_struct in structs { + let path = context.ctx.abs_struct_path(&ref_struct.base.internal_name); + let mut file = File::create(&path).unwrap_or_else(|e| { + fatal(&format!( + "Failed to create struct file '{}': {e}", + path.to_str().unwrap_or("") + )) + }); + context.write_struct(&mut file, &ref_struct).unwrap(); + } +} + +fn write_lua_files(context: &Context, doc: &LuaDocumentation) { + remove_files_in_folder(&context.abs_lua_path); + + let context = LuaContext::new(context); + + for module in &doc.modules { + let path = context.ctx.abs_lua_module_path(&module.base.internal_name); + let mut file = File::create(&path).unwrap_or_else(|e| { + fatal(&format!( + "Failed to create lua module file '{}': {e}", + path.to_str().unwrap_or("") + )) + }); + context.write_module(&mut file, module).unwrap(); + } +} + +fn write_doc_files_to_nav<'a, 'b, T: Iterator>( + nav_content: &mut Vec, + prefix: &str, + files: T, +) { + for (title, path) in files { + writeln!(nav_content, "{prefix} xref:{path}[{title}]").unwrap(); + } +} + +fn update_navigation_file(context: &Context) { + let file = File::open(context.config.abs_nav_file_path()) + .unwrap_or_else(|e| fatal(&format!("Unable to read navigation file: {e}"))); + let file_buf = BufReader::new(file); + + let regex = Regex::new( + r"^\s*//\s+FIN((Reflection)|(Lua))Documentation((Begin\s+(\*+))|(End))\s+//\s*$", + ) + .unwrap(); + + let mut reflection_prefix: Option = None; + let mut lua_prefix: Option = None; + let mut new_contents = Vec::new(); + for line in file_buf.lines() { + let line = if let Ok(line) = line { + line + } else { + continue; + }; + + if let Some(captures) = regex.captures(&line) { + if captures.get(2).is_some() { + // a reflection begin/end + if let Some(capture) = captures.get(6) { + reflection_prefix = Some(capture.as_str().to_string()); + writeln!(&mut new_contents, "{line}").unwrap(); + } else if let Some(prefix) = reflection_prefix { + writeln!(&mut new_contents, "{prefix} Classes").unwrap(); + write_doc_files_to_nav( + &mut new_contents, + &(prefix.clone() + "*"), + context.class_pages.iter(), + ); + writeln!(&mut new_contents, "{prefix} Structs").unwrap(); + write_doc_files_to_nav( + &mut new_contents, + &(prefix + "*"), + context.struct_pages.iter(), + ); + reflection_prefix = None; + } + } else if captures.get(3).is_some() { + if let Some(capture) = captures.get(6) { + lua_prefix = Some(capture.as_str().to_string()); + writeln!(&mut new_contents, "{line}").unwrap(); + } else if let Some(prefix) = lua_prefix { + write_doc_files_to_nav(&mut new_contents, &prefix, context.lua_pages.iter()); + lua_prefix = None; + } + } + }; + + if reflection_prefix.is_none() && lua_prefix.is_none() { + writeln!(&mut new_contents, "{line}").unwrap(); + } + } + + std::fs::write(context.config.abs_nav_file_path(), new_contents) + .unwrap_or_else(|e| fatal(&format!("Unable to write changes to navigation file: {e}"))); +} + +fn exec_cmd(input: &Path, config: Config) { + let input = std::path::absolute(input).unwrap(); + + let doc = Documentation::load(&input) + .unwrap_or_else(|e| fatal(&format!("Unable to load documentation: {e}"))); + + let context = Context::new(config, &doc); + + write_reflection_files(&context, &doc.reflection); + write_lua_files(&context, &doc.lua); + update_navigation_file(&context); +} + +fn main() { + let args: Vec = std::env::args().collect(); + let program = args[0].clone(); + + let mut opts = getopts::Options::new(); + opts.optflag("h", "help", "print this help menu"); + opts.optopt("i", "config", "set the path to the config file", "NAME"); + let matches = match opts.parse(&args[1..]) { + Ok(m) => m, + Err(f) => panic!("{}", f.to_string()), + }; + if matches.opt_present("h") { + let brief = format!("Usage: {} FILE [options]", program); + print!("{}", opts.usage(&brief)); + return; + } + let input = matches + .free + .get(0) + .unwrap_or_else(|| fatal("No documentation input JSON file provided!")); + let config_path = PathBuf::from( + matches + .opt_str("i") + .unwrap_or("FINDocumentation.toml".to_string()), + ); + + let config = Config::load(&config_path) + .unwrap_or_else(|e| fatal(&format!("Failed ot load config file: {e}"))); + + exec_cmd(Path::new(&input), config); +} diff --git a/Tools/DocumentationCLI/src/reflection.rs b/Tools/DocumentationCLI/src/reflection.rs new file mode 100644 index 000000000..35a594220 --- /dev/null +++ b/Tools/DocumentationCLI/src/reflection.rs @@ -0,0 +1,509 @@ +use crate::context::Context; +use crate::util::prefix_string_lines; +use serde::Deserialize; +use std::borrow::Borrow; +use std::fs::File; +use std::io::{Result, Write}; + +#[derive(Deserialize, Debug)] +#[serde(tag = "type")] +pub enum ReflectionValueType { + Bool, + Int, + Float, + String, + Object { + subclass: Option, + }, + Trace { + subclass: Option, + }, + Struct { + inner: Option, + }, + Class { + subclass: Option, + }, + Array { + inner: Option>, + }, +} + +#[derive(Deserialize, Debug, Eq, PartialEq)] +pub enum ReflectionPropertyFlag { + Attrib, + ReadOnly, + Param, + OutParam, + RetVal, + #[serde(alias = "RT_Sync")] + RTSync, + #[serde(alias = "RT_Parallel")] + RTParallel, + #[serde(alias = "RT_Async")] + RTAsync, + ClassProp, + StaticProp, +} + +#[derive(Deserialize, Debug)] +pub struct ReflectionBase { + #[serde(alias = "internalName")] + pub internal_name: String, + #[serde(alias = "displayName")] + pub display_name: Option, + pub description: String, +} + +impl ReflectionBase { + pub fn display_name(&self) -> &str { + self.display_name.as_deref().unwrap_or(&self.internal_name) + } + + pub fn name_adoc(&self) -> String { + if let Some(display_name) = &self.display_name { + format!("*{}* `{}`", display_name, self.internal_name) + } else { + format!("`{}`", self.internal_name) + } + } + + pub fn header_name_adoc(&self) -> String { + format!("`{}`", self.internal_name) + } +} + +#[derive(Deserialize, Debug)] +pub struct ReflectionProperty { + #[serde(flatten)] + base: ReflectionBase, + #[serde(alias = "type")] + value_type: ReflectionValueType, + flags: Vec, +} + +#[derive(Deserialize, Debug, Eq, PartialEq)] +pub enum ReflectionFunctionFlag { + VarArgs, + #[serde(alias = "RT_Sync")] + RTSync, + #[serde(alias = "RT_Parallel")] + RTParallel, + #[serde(alias = "RT_Async")] + RTAsync, + MemberFunc, + ClassFunc, + StaticFunc, + VarRets, +} + +#[derive(Deserialize, Debug)] +pub struct ReflectionFunction { + #[serde(flatten)] + base: ReflectionBase, + parameters: Vec, + flags: Vec, +} + +#[derive(Deserialize, Debug)] +pub struct ReflectionStruct { + #[serde(flatten)] + pub base: ReflectionBase, + pub parent: Option, + pub properties: Vec, + pub functions: Vec, +} + +#[derive(Deserialize, Debug)] +pub struct ReflectionSignal { + #[serde(flatten)] + base: ReflectionBase, + parameters: Vec, + #[serde(alias = "isVarArgs")] + is_var_args: bool, +} + +#[derive(Deserialize, Debug)] +pub struct ReflectionClass { + #[serde(flatten)] + pub reflection_struct: ReflectionStruct, + pub signals: Vec, +} + +#[derive(Deserialize, Debug)] +pub struct ReflectionDocumentation { + pub classes: Vec, + pub structs: Vec, +} + +pub struct ReflectionContext<'a> { + pub ctx: &'a Context, +} + +impl<'a> ReflectionContext<'a> { + pub fn new(context: &'a Context) -> Self { + Self { ctx: context } + } + + fn get_value_type(&self, value: &ReflectionValueType) -> String { + match value { + ReflectionValueType::Bool => "Bool".to_string(), + ReflectionValueType::Int => "Int".to_string(), + ReflectionValueType::Float => "Float".to_string(), + ReflectionValueType::String => "String".to_string(), + ReflectionValueType::Object { subclass } => { + format!("Object<{}>", self.ctx.xref_class(subclass)) + } + ReflectionValueType::Trace { subclass } => { + format!("Trace<{}>", self.ctx.xref_class(subclass)) + } + ReflectionValueType::Struct { inner } => { + if let Some(inner) = inner { + format!("Struct<{}>", self.ctx.xref_struct(&Some(inner.as_str()))) + } else { + "Struct".to_string() + } + } + ReflectionValueType::Class { subclass } => { + format!("Class<{}>", self.ctx.xref_class(subclass)) + } + ReflectionValueType::Array { inner } => { + if let Some(inner) = inner { + format!("Array<{}>", self.get_value_type(inner)) + } else { + "Array".to_string() + } + } + } + } + + fn write_property(&self, file: &mut File, property: &ReflectionProperty) -> Result<()> { + let flags: String = property + .flags + .iter() + .map(|f| match f { + ReflectionPropertyFlag::ReadOnly => { + Some("ReadOnly") + } + ReflectionPropertyFlag::RTSync => { + Some("RuntimeSync") + } + ReflectionPropertyFlag::RTParallel => { + Some("RuntimeParallel") + } + ReflectionPropertyFlag::RTAsync => { + Some("RuntimeAsync") + } + ReflectionPropertyFlag::ClassProp => { + Some("ClassProp") + } + ReflectionPropertyFlag::StaticProp => { + Some("StaticProp") + } + _ => None, + }) + .flatten() + .intersperse(" ") + .collect(); + + let display_name_table = if let Some(display_name) = &property.base.display_name { + format!("\n| Display Name\n| {display_name}") + } else { + "".to_string() + }; + + file.write( + indoc::formatdoc!( + r#" + === {} : {} + + {} + + [cols="1,5a"] + |=== + | Flags + | +++{flags}+++ + {display_name_table} + |=== + + "#, + property.base.header_name_adoc(), + self.get_value_type(&property.value_type), + property.base.description + ) + .as_bytes(), + )?; + + Ok(()) + } + + fn write_property_table>( + &self, + file: &mut File, + properties: &[P], + ) -> Result<()> { + writeln!(file, r#"[%header,cols="1,1,4a"]"#)?; + writeln!(file, r#"|==="#)?; + writeln!(file, r#"|Name |Type |Description"#)?; + writeln!(file)?; + + for property in properties { + let property = property.borrow(); + writeln!(file, "| {}", property.base.name_adoc())?; + writeln!(file, "| {}", self.get_value_type(&property.value_type))?; + writeln!( + file, + "| {}", + prefix_string_lines(" ", &property.base.description) + )?; + writeln!(file)?; + } + + writeln!(file, r"|===")?; + + Ok(()) + } + + fn write_function(&self, file: &mut File, function: &ReflectionFunction) -> Result<()> { + let (parameters, return_values): (Vec<_>, Vec<_>) = function + .parameters + .iter() + .map(|p| { + ( + p, + format!( + "{} : {}", + p.base.name_adoc(), + self.get_value_type(&p.value_type) + ), + ) + }) + .partition(|(p, _)| !p.flags.contains(&ReflectionPropertyFlag::OutParam)); + let (parameter_props, mut parameter_strings): (Vec<_>, Vec<_>) = + parameters.into_iter().unzip(); + let (return_value_props, mut return_value_strings): (Vec<_>, Vec<_>) = + return_values.into_iter().unzip(); + if function.flags.contains(&ReflectionFunctionFlag::VarArgs) { + parameter_strings.push("...".to_string()); + } + if function.flags.contains(&ReflectionFunctionFlag::VarRets) { + return_value_strings.push("...".to_string()); + } + let parameters = parameter_strings.join(", "); + let return_values = match &return_value_strings[..] { + [] => "".to_string(), + [s] => format!(" -> {}", s), + _ => format!(" -> ({})", return_value_strings.join(", ")), + }; + + let flags: String = function + .flags + .iter() + .map(|f| match f { + ReflectionFunctionFlag::VarArgs => { + "VarArgs" + } + ReflectionFunctionFlag::RTSync => { + "RuntimeSync" + } + ReflectionFunctionFlag::RTParallel => { + "RuntimeParallel" + } + ReflectionFunctionFlag::RTAsync => { + "RuntimeAsync" + } + ReflectionFunctionFlag::MemberFunc => { + "MemberFunc" + } + ReflectionFunctionFlag::ClassFunc => { + "ClassFunc" + } + ReflectionFunctionFlag::StaticFunc => { + "StaticFunc" + } + ReflectionFunctionFlag::VarRets => { + "VarReturns" + } + }) + .intersperse(" ") + .collect(); + + let display_name_table = if let Some(display_name) = &function.base.display_name { + format!("\n| Display Name\n| {display_name}") + } else { + "".to_string() + }; + + file.write( + indoc::formatdoc!( + r#" + === {} ({parameters}){return_values} + + {} + + [cols="1,5a"] + |=== + | Flags + | +++{flags}+++ + {display_name_table} + |=== + + "#, + function.base.header_name_adoc(), + function.base.description, + ) + .as_bytes(), + )?; + + if !parameter_props.is_empty() { + writeln!(file, "Parameters::")?; + self.write_property_table(file, ¶meter_props)?; + writeln!(file)?; + } + + if !return_value_props.is_empty() { + writeln!(file, "Return Values::")?; + self.write_property_table(file, &return_value_props)?; + writeln!(file)?; + } + + Ok(()) + } + + fn write_file_base(&self, file: &mut File, base: &ReflectionBase) -> Result<()> { + let title = base.display_name(); + let description = &base.description; + + file.write( + indoc::formatdoc!( + r" + = {title} + + {description} + + " + ) + .as_bytes(), + )?; + + Ok(()) + } + + pub(crate) fn write_struct( + &self, + file: &mut File, + ref_struct: &ReflectionStruct, + ) -> Result<()> { + self.write_file_base(file, &ref_struct.base)?; + + if !ref_struct.properties.is_empty() { + writeln!(file, "== Properties")?; + writeln!(file)?; + + for property in &ref_struct.properties { + self.write_property(file, property)?; + } + + writeln!(file)?; + } + + if !ref_struct.functions.is_empty() { + writeln!(file, "== Functions")?; + writeln!(file)?; + + for function in &ref_struct.functions { + self.write_function(file, function)?; + } + + writeln!(file)?; + } + + Ok(()) + } + + fn write_signal(&self, file: &mut File, signal: &ReflectionSignal) -> Result<()> { + let mut parameters = signal + .parameters + .iter() + .map(|p| { + format!( + "_{}_ {}", + self.get_value_type(&p.value_type), + p.base.name_adoc() + ) + }) + .collect::>(); + if signal.is_var_args { + parameters.push("...".to_string()); + } + let parameters = parameters.join(", "); + + let name = signal.base.header_name_adoc(); + let description = &signal.base.description; + + file.write( + indoc::formatdoc!( + r" + === {name} ({parameters}) + + {description} + + " + ) + .as_bytes(), + )?; + + if !signal.parameters.is_empty() { + writeln!(file, "Parameters::")?; + self.write_property_table(file, &signal.parameters)?; + writeln!(file)?; + } + + Ok(()) + } + + pub(crate) fn write_class(&self, file: &mut File, ref_class: &ReflectionClass) -> Result<()> { + self.write_file_base(file, &ref_class.reflection_struct.base)?; + + writeln!(file, "// tag::interface[]")?; + writeln!(file)?; + + if !ref_class.reflection_struct.properties.is_empty() { + writeln!(file, "== Properties")?; + writeln!(file)?; + + for property in &ref_class.reflection_struct.properties { + self.write_property(file, property)?; + } + + writeln!(file)?; + } + + if !ref_class.reflection_struct.functions.is_empty() { + writeln!(file, "== Functions")?; + writeln!(file)?; + + for function in &ref_class.reflection_struct.functions { + self.write_function(file, function)?; + } + + writeln!(file)?; + } + + if !ref_class.signals.is_empty() { + writeln!(file, "== Signals")?; + writeln!(file)?; + + for signal in &ref_class.signals { + self.write_signal(file, &signal)?; + } + + writeln!(file)?; + } + + writeln!(file, "// end::interface[]")?; + writeln!(file)?; + + Ok(()) + } +} diff --git a/Tools/DocumentationCLI/src/util.rs b/Tools/DocumentationCLI/src/util.rs new file mode 100644 index 000000000..9e933d342 --- /dev/null +++ b/Tools/DocumentationCLI/src/util.rs @@ -0,0 +1,16 @@ +use std::ffi::OsStr; +use std::path::Path; + +pub fn prefix_string_lines(prefix: &str, string: &str) -> String { + string + .lines() + .intersperse(&("\n".to_string() + prefix)) + .collect() +} + +pub fn path_to_forward_slash(path: &Path) -> Option { + path.iter() + .intersperse(OsStr::new("/")) + .map(|s| s.to_str()) + .collect() +} diff --git a/docs/FINDocumentation.toml b/docs/FINDocumentation.toml new file mode 100644 index 000000000..1566366a2 --- /dev/null +++ b/docs/FINDocumentation.toml @@ -0,0 +1,3 @@ +nav_file_path = "modules/ROOT/nav.adoc" +reflection_folder = "modules/ROOT/pages/reflection" +lua_folder = "modules/ROOT/pages/lua/api"