├── .ameba.yml ├── .github └── workflows │ ├── ci.yml │ ├── nightly.yml │ └── release.yml ├── .gitignore ├── LICENSE ├── README.md ├── assets ├── demo_1.png ├── demo_2.png ├── demo_3.png └── demo_4.png ├── bucket └── docr.json ├── shard.lock ├── shard.yml └── src ├── commands ├── about.cr ├── add.cr ├── base.cr ├── check.cr ├── help.cr ├── info.cr ├── list.cr ├── remove.cr ├── search.cr ├── tree.cr └── version.cr ├── docr.cr ├── formatters ├── base.cr ├── default │ ├── info.cr │ ├── signature.cr │ └── tree.cr └── signature.cr ├── library.cr ├── main.cr └── renderer.cr /.ameba.yml: -------------------------------------------------------------------------------- 1 | Globs: 2 | - src/**/*.cr 3 | - spec/**/*.cr 4 | 5 | Documentation/Documentation: 6 | Enabled: false 7 | 8 | Documentation/DocumentationAdmonition: 9 | Enabled: false 10 | 11 | Metrics/CyclomaticComplexity: 12 | Enabled: false 13 | 14 | Naming/BlockParameterName: 15 | Enabled: false 16 | 17 | # There is nothing to prove that this affects performance 18 | Performance/AnyInsteadOfEmpty: 19 | Enabled: false 20 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | 8 | paths: 9 | - src/ 10 | 11 | pull_request: 12 | branches: 13 | - main 14 | 15 | permissions: 16 | checks: write 17 | 18 | jobs: 19 | test: 20 | runs-on: ubuntu-latest 21 | steps: 22 | - name: Checkout 23 | uses: actions/checkout@v4 24 | 25 | - name: Install Crystal 26 | uses: crystal-lang/install-crystal@v1 27 | with: 28 | crystal: latest 29 | 30 | - name: Install Dependencies 31 | run: shards install --production 32 | 33 | - name: Install Ameba 34 | uses: crystal-ameba/github-action@v0.9.0 35 | env: 36 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 37 | 38 | - name: Check Format 39 | run: crystal tool format --check 40 | 41 | - name: Check Unreachable 42 | run: crystal tool unreachable src/main.cr --check 43 | -------------------------------------------------------------------------------- /.github/workflows/nightly.yml: -------------------------------------------------------------------------------- 1 | name: Nightly 2 | 3 | on: 4 | # temporary 5 | push: 6 | tags: 7 | - nightly 8 | 9 | schedule: 10 | # - cron: 0 6 * * 6 11 | - cron: 0 22 * * */2 12 | 13 | permissions: 14 | actions: write 15 | contents: write 16 | 17 | env: 18 | VERSION: 1.0.0 19 | 20 | jobs: 21 | linux: 22 | runs-on: ubuntu-latest 23 | steps: 24 | - name: Checkout 25 | uses: actions/checkout@v4 26 | 27 | - name: Install Crystal 28 | uses: crystal-lang/install-crystal@v1 29 | with: 30 | crystal: nightly 31 | 32 | - name: Install Dependencies 33 | run: shards install --production 34 | 35 | - name: Compile Binaries 36 | run: | 37 | crystal build src/main.cr --debug -o docr 38 | tar -zcf docr-${{ env.VERSION }}-nightly-linux-x86_64.tar.gz docr 39 | 40 | - name: Upload Artifacts 41 | uses: actions/upload-artifact@v4 42 | with: 43 | name: docr-linux 44 | path: | 45 | docr 46 | docr-${{ env.VERSION }}-nightly-linux-x86_64.tar.gz 47 | 48 | windows: 49 | needs: linux 50 | runs-on: windows-latest 51 | steps: 52 | - name: Checkout 53 | uses: actions/checkout@v4 54 | 55 | - name: Install Crystal 56 | uses: crystal-lang/install-crystal@v1 57 | with: 58 | crystal: nightly 59 | 60 | - name: Install Dependencies 61 | run: shards install --production 62 | 63 | - name: Compile Binaries 64 | run: | 65 | crystal build src\main.cr --debug -o docr.exe 66 | $compress = @{ 67 | Path = "docr.exe", "docr.pdb", "*.dll" 68 | DestinationPath = "docr-${{ env.VERSION }}-nightly-windows-x86_64-msvc.zip" 69 | } 70 | Compress-Archive @compress 71 | 72 | - name: Upload Artifacts 73 | uses: actions/upload-artifact@v4 74 | with: 75 | name: docr-windows 76 | path: | 77 | docr.exe 78 | docr.pdb 79 | docr-${{ env.VERSION }}-nightly-windows-x86_64-msvc.zip 80 | 81 | release: 82 | needs: windows 83 | runs-on: ubuntu-latest 84 | steps: 85 | - name: Checkout 86 | uses: actions/checkout@v4 87 | 88 | - name: Download Artifacts 89 | uses: actions/download-artifact@v4 90 | with: 91 | path: artifacts/ 92 | pattern: docr-* 93 | merge-multiple: true 94 | 95 | - name: Prepare Artifacts 96 | run: | 97 | mv artifacts/* . 98 | sha256sum docr docr.exe docr.pdb > checksums.txt 99 | 100 | - name: Create Release 101 | env: 102 | GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} 103 | 104 | run: | 105 | gh release view nightly &>/dev/null && gh release delete nightly -y 106 | gh release create nightly -pt Nightly --notes "Nightly release for v${{ env.VERSION }} ($(date +%F))." 107 | gh release upload nightly checksums.txt 108 | gh release upload nightly docr-${{ env.VERSION }}-nightly-linux-x86_64.tar.gz 109 | gh release upload nightly docr-${{ env.VERSION }}-nightly-windows-x86_64-msvc.zip 110 | -------------------------------------------------------------------------------- /.github/workflows/release.yml: -------------------------------------------------------------------------------- 1 | name: Release 2 | 3 | on: 4 | push: 5 | tags: 6 | - "v*" 7 | 8 | permissions: 9 | actions: write 10 | contents: write 11 | 12 | jobs: 13 | linux: 14 | runs-on: ubuntu-latest 15 | steps: 16 | - name: Checkout 17 | uses: actions/checkout@v4 18 | 19 | - name: Install Crystal 20 | uses: crystal-lang/install-crystal@v1 21 | with: 22 | crystal: latest 23 | 24 | - name: Install Dependencies 25 | run: shards install --production 26 | 27 | - name: Compile Binaries 28 | run: | 29 | crystal build src/main.cr --no-debug --release -o docr 30 | tar -zcf docr-${{ github.ref_name }}-linux-x86_64.tar.gz docr 31 | 32 | - name: Upload Artifacts 33 | uses: actions/upload-artifact@v4 34 | with: 35 | name: docr-linux 36 | path: | 37 | docr 38 | docr-${{ github.ref_name }}-linux-x86_64.tar.gz 39 | 40 | windows: 41 | needs: linux 42 | runs-on: windows-latest 43 | steps: 44 | - name: Checkout 45 | uses: actions/checkout@v4 46 | 47 | - name: Install Crystal 48 | uses: crystal-lang/install-crystal@v1 49 | with: 50 | crystal: latest 51 | 52 | - name: Install Dependencies 53 | run: shards install --production 54 | 55 | - name: Compile Binaries 56 | run: | 57 | crystal build src\main.cr --no-debug --release -o docr.exe 58 | $compress = @{ 59 | Path = "docr.exe", "*.dll" 60 | DestinationPath = "docr-${{ github.ref_name }}-windows-x86_64-msvc.zip" 61 | } 62 | Compress-Archive @compress 63 | 64 | - name: Upload Artifacts 65 | uses: actions/upload-artifact@v4 66 | with: 67 | name: docr-windows 68 | path: | 69 | docr.exe 70 | docr-${{ github.ref_name }}-windows-x86_64-msvc.zip 71 | 72 | release: 73 | needs: windows 74 | runs-on: ubuntu-latest 75 | steps: 76 | - name: Checkout 77 | uses: actions/checkout@v4 78 | 79 | - name: Download Artifacts 80 | uses: actions/download-artifact@v4 81 | with: 82 | path: artifacts/ 83 | pattern: docr-* 84 | merge-multiple: true 85 | 86 | - name: Prepare Artifacts 87 | run: | 88 | mv artifacts/* . 89 | sha256sum docr docr.exe > checksums.txt 90 | 91 | - name: Create Release 92 | env: 93 | GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} 94 | 95 | run: | 96 | gh release create ${{ github.ref_name }} -pt v${{ github.ref_name }} 97 | gh release upload ${{ github.ref_name }} checksums.txt 98 | gh release upload ${{ github.ref_name }} docr-${{ github.ref_name }}-linux-x86_64.tar.gz 99 | gh release upload ${{ github.ref_name }} docr-${{ github.ref_name }}-windows-x86_64-msvc.zip 100 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Workspace configurations 2 | /docs/ 3 | /lib/ 4 | /bin/ 5 | /.shards/ 6 | /.vscode/ 7 | 8 | # Binaries for programs and plugins 9 | /build 10 | *.exe 11 | *.dll 12 | *.so 13 | *.dylib 14 | 15 | # Test binaries and files 16 | /test 17 | /samples 18 | *.test 19 | *.test.* 20 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Mozilla Public License Version 2.0 2 | ================================== 3 | 4 | 1. Definitions 5 | -------------- 6 | 7 | 1.1. "Contributor" 8 | means each individual or legal entity that creates, contributes to 9 | the creation of, or owns Covered Software. 10 | 11 | 1.2. "Contributor Version" 12 | means the combination of the Contributions of others (if any) used 13 | by a Contributor and that particular Contributor's Contribution. 14 | 15 | 1.3. "Contribution" 16 | means Covered Software of a particular Contributor. 17 | 18 | 1.4. "Covered Software" 19 | means Source Code Form to which the initial Contributor has attached 20 | the notice in Exhibit A, the Executable Form of such Source Code 21 | Form, and Modifications of such Source Code Form, in each case 22 | including portions thereof. 23 | 24 | 1.5. "Incompatible With Secondary Licenses" 25 | means 26 | 27 | (a) that the initial Contributor has attached the notice described 28 | in Exhibit B to the Covered Software; or 29 | 30 | (b) that the Covered Software was made available under the terms of 31 | version 1.1 or earlier of the License, but not also under the 32 | terms of a Secondary License. 33 | 34 | 1.6. "Executable Form" 35 | means any form of the work other than Source Code Form. 36 | 37 | 1.7. "Larger Work" 38 | means a work that combines Covered Software with other material, in 39 | a separate file or files, that is not Covered Software. 40 | 41 | 1.8. "License" 42 | means this document. 43 | 44 | 1.9. "Licensable" 45 | means having the right to grant, to the maximum extent possible, 46 | whether at the time of the initial grant or subsequently, any and 47 | all of the rights conveyed by this License. 48 | 49 | 1.10. "Modifications" 50 | means any of the following: 51 | 52 | (a) any file in Source Code Form that results from an addition to, 53 | deletion from, or modification of the contents of Covered 54 | Software; or 55 | 56 | (b) any new file in Source Code Form that contains any Covered 57 | Software. 58 | 59 | 1.11. "Patent Claims" of a Contributor 60 | means any patent claim(s), including without limitation, method, 61 | process, and apparatus claims, in any patent Licensable by such 62 | Contributor that would be infringed, but for the grant of the 63 | License, by the making, using, selling, offering for sale, having 64 | made, import, or transfer of either its Contributions or its 65 | Contributor Version. 66 | 67 | 1.12. "Secondary License" 68 | means either the GNU General Public License, Version 2.0, the GNU 69 | Lesser General Public License, Version 2.1, the GNU Affero General 70 | Public License, Version 3.0, or any later versions of those 71 | licenses. 72 | 73 | 1.13. "Source Code Form" 74 | means the form of the work preferred for making modifications. 75 | 76 | 1.14. "You" (or "Your") 77 | means an individual or a legal entity exercising rights under this 78 | License. For legal entities, "You" includes any entity that 79 | controls, is controlled by, or is under common control with You. For 80 | purposes of this definition, "control" means (a) the power, direct 81 | or indirect, to cause the direction or management of such entity, 82 | whether by contract or otherwise, or (b) ownership of more than 83 | fifty percent (50%) of the outstanding shares or beneficial 84 | ownership of such entity. 85 | 86 | 2. License Grants and Conditions 87 | -------------------------------- 88 | 89 | 2.1. Grants 90 | 91 | Each Contributor hereby grants You a world-wide, royalty-free, 92 | non-exclusive license: 93 | 94 | (a) under intellectual property rights (other than patent or trademark) 95 | Licensable by such Contributor to use, reproduce, make available, 96 | modify, display, perform, distribute, and otherwise exploit its 97 | Contributions, either on an unmodified basis, with Modifications, or 98 | as part of a Larger Work; and 99 | 100 | (b) under Patent Claims of such Contributor to make, use, sell, offer 101 | for sale, have made, import, and otherwise transfer either its 102 | Contributions or its Contributor Version. 103 | 104 | 2.2. Effective Date 105 | 106 | The licenses granted in Section 2.1 with respect to any Contribution 107 | become effective for each Contribution on the date the Contributor first 108 | distributes such Contribution. 109 | 110 | 2.3. Limitations on Grant Scope 111 | 112 | The licenses granted in this Section 2 are the only rights granted under 113 | this License. No additional rights or licenses will be implied from the 114 | distribution or licensing of Covered Software under this License. 115 | Notwithstanding Section 2.1(b) above, no patent license is granted by a 116 | Contributor: 117 | 118 | (a) for any code that a Contributor has removed from Covered Software; 119 | or 120 | 121 | (b) for infringements caused by: (i) Your and any other third party's 122 | modifications of Covered Software, or (ii) the combination of its 123 | Contributions with other software (except as part of its Contributor 124 | Version); or 125 | 126 | (c) under Patent Claims infringed by Covered Software in the absence of 127 | its Contributions. 128 | 129 | This License does not grant any rights in the trademarks, service marks, 130 | or logos of any Contributor (except as may be necessary to comply with 131 | the notice requirements in Section 3.4). 132 | 133 | 2.4. Subsequent Licenses 134 | 135 | No Contributor makes additional grants as a result of Your choice to 136 | distribute the Covered Software under a subsequent version of this 137 | License (see Section 10.2) or under the terms of a Secondary License (if 138 | permitted under the terms of Section 3.3). 139 | 140 | 2.5. Representation 141 | 142 | Each Contributor represents that the Contributor believes its 143 | Contributions are its original creation(s) or it has sufficient rights 144 | to grant the rights to its Contributions conveyed by this License. 145 | 146 | 2.6. Fair Use 147 | 148 | This License is not intended to limit any rights You have under 149 | applicable copyright doctrines of fair use, fair dealing, or other 150 | equivalents. 151 | 152 | 2.7. Conditions 153 | 154 | Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted 155 | in Section 2.1. 156 | 157 | 3. Responsibilities 158 | ------------------- 159 | 160 | 3.1. Distribution of Source Form 161 | 162 | All distribution of Covered Software in Source Code Form, including any 163 | Modifications that You create or to which You contribute, must be under 164 | the terms of this License. You must inform recipients that the Source 165 | Code Form of the Covered Software is governed by the terms of this 166 | License, and how they can obtain a copy of this License. You may not 167 | attempt to alter or restrict the recipients' rights in the Source Code 168 | Form. 169 | 170 | 3.2. Distribution of Executable Form 171 | 172 | If You distribute Covered Software in Executable Form then: 173 | 174 | (a) such Covered Software must also be made available in Source Code 175 | Form, as described in Section 3.1, and You must inform recipients of 176 | the Executable Form how they can obtain a copy of such Source Code 177 | Form by reasonable means in a timely manner, at a charge no more 178 | than the cost of distribution to the recipient; and 179 | 180 | (b) You may distribute such Executable Form under the terms of this 181 | License, or sublicense it under different terms, provided that the 182 | license for the Executable Form does not attempt to limit or alter 183 | the recipients' rights in the Source Code Form under this License. 184 | 185 | 3.3. Distribution of a Larger Work 186 | 187 | You may create and distribute a Larger Work under terms of Your choice, 188 | provided that You also comply with the requirements of this License for 189 | the Covered Software. If the Larger Work is a combination of Covered 190 | Software with a work governed by one or more Secondary Licenses, and the 191 | Covered Software is not Incompatible With Secondary Licenses, this 192 | License permits You to additionally distribute such Covered Software 193 | under the terms of such Secondary License(s), so that the recipient of 194 | the Larger Work may, at their option, further distribute the Covered 195 | Software under the terms of either this License or such Secondary 196 | License(s). 197 | 198 | 3.4. Notices 199 | 200 | You may not remove or alter the substance of any license notices 201 | (including copyright notices, patent notices, disclaimers of warranty, 202 | or limitations of liability) contained within the Source Code Form of 203 | the Covered Software, except that You may alter any license notices to 204 | the extent required to remedy known factual inaccuracies. 205 | 206 | 3.5. Application of Additional Terms 207 | 208 | You may choose to offer, and to charge a fee for, warranty, support, 209 | indemnity or liability obligations to one or more recipients of Covered 210 | Software. However, You may do so only on Your own behalf, and not on 211 | behalf of any Contributor. You must make it absolutely clear that any 212 | such warranty, support, indemnity, or liability obligation is offered by 213 | You alone, and You hereby agree to indemnify every Contributor for any 214 | liability incurred by such Contributor as a result of warranty, support, 215 | indemnity or liability terms You offer. You may include additional 216 | disclaimers of warranty and limitations of liability specific to any 217 | jurisdiction. 218 | 219 | 4. Inability to Comply Due to Statute or Regulation 220 | --------------------------------------------------- 221 | 222 | If it is impossible for You to comply with any of the terms of this 223 | License with respect to some or all of the Covered Software due to 224 | statute, judicial order, or regulation then You must: (a) comply with 225 | the terms of this License to the maximum extent possible; and (b) 226 | describe the limitations and the code they affect. Such description must 227 | be placed in a text file included with all distributions of the Covered 228 | Software under this License. Except to the extent prohibited by statute 229 | or regulation, such description must be sufficiently detailed for a 230 | recipient of ordinary skill to be able to understand it. 231 | 232 | 5. Termination 233 | -------------- 234 | 235 | 5.1. The rights granted under this License will terminate automatically 236 | if You fail to comply with any of its terms. However, if You become 237 | compliant, then the rights granted under this License from a particular 238 | Contributor are reinstated (a) provisionally, unless and until such 239 | Contributor explicitly and finally terminates Your grants, and (b) on an 240 | ongoing basis, if such Contributor fails to notify You of the 241 | non-compliance by some reasonable means prior to 60 days after You have 242 | come back into compliance. Moreover, Your grants from a particular 243 | Contributor are reinstated on an ongoing basis if such Contributor 244 | notifies You of the non-compliance by some reasonable means, this is the 245 | first time You have received notice of non-compliance with this License 246 | from such Contributor, and You become compliant prior to 30 days after 247 | Your receipt of the notice. 248 | 249 | 5.2. If You initiate litigation against any entity by asserting a patent 250 | infringement claim (excluding declaratory judgment actions, 251 | counter-claims, and cross-claims) alleging that a Contributor Version 252 | directly or indirectly infringes any patent, then the rights granted to 253 | You by any and all Contributors for the Covered Software under Section 254 | 2.1 of this License shall terminate. 255 | 256 | 5.3. In the event of termination under Sections 5.1 or 5.2 above, all 257 | end user license agreements (excluding distributors and resellers) which 258 | have been validly granted by You or Your distributors under this License 259 | prior to termination shall survive termination. 260 | 261 | ************************************************************************ 262 | * * 263 | * 6. Disclaimer of Warranty * 264 | * ------------------------- * 265 | * * 266 | * Covered Software is provided under this License on an "as is" * 267 | * basis, without warranty of any kind, either expressed, implied, or * 268 | * statutory, including, without limitation, warranties that the * 269 | * Covered Software is free of defects, merchantable, fit for a * 270 | * particular purpose or non-infringing. The entire risk as to the * 271 | * quality and performance of the Covered Software is with You. * 272 | * Should any Covered Software prove defective in any respect, You * 273 | * (not any Contributor) assume the cost of any necessary servicing, * 274 | * repair, or correction. This disclaimer of warranty constitutes an * 275 | * essential part of this License. No use of any Covered Software is * 276 | * authorized under this License except under this disclaimer. * 277 | * * 278 | ************************************************************************ 279 | 280 | ************************************************************************ 281 | * * 282 | * 7. Limitation of Liability * 283 | * -------------------------- * 284 | * * 285 | * Under no circumstances and under no legal theory, whether tort * 286 | * (including negligence), contract, or otherwise, shall any * 287 | * Contributor, or anyone who distributes Covered Software as * 288 | * permitted above, be liable to You for any direct, indirect, * 289 | * special, incidental, or consequential damages of any character * 290 | * including, without limitation, damages for lost profits, loss of * 291 | * goodwill, work stoppage, computer failure or malfunction, or any * 292 | * and all other commercial damages or losses, even if such party * 293 | * shall have been informed of the possibility of such damages. This * 294 | * limitation of liability shall not apply to liability for death or * 295 | * personal injury resulting from such party's negligence to the * 296 | * extent applicable law prohibits such limitation. Some * 297 | * jurisdictions do not allow the exclusion or limitation of * 298 | * incidental or consequential damages, so this exclusion and * 299 | * limitation may not apply to You. * 300 | * * 301 | ************************************************************************ 302 | 303 | 8. Litigation 304 | ------------- 305 | 306 | Any litigation relating to this License may be brought only in the 307 | courts of a jurisdiction where the defendant maintains its principal 308 | place of business and such litigation shall be governed by laws of that 309 | jurisdiction, without reference to its conflict-of-law provisions. 310 | Nothing in this Section shall prevent a party's ability to bring 311 | cross-claims or counter-claims. 312 | 313 | 9. Miscellaneous 314 | ---------------- 315 | 316 | This License represents the complete agreement concerning the subject 317 | matter hereof. If any provision of this License is held to be 318 | unenforceable, such provision shall be reformed only to the extent 319 | necessary to make it enforceable. Any law or regulation which provides 320 | that the language of a contract shall be construed against the drafter 321 | shall not be used to construe this License against a Contributor. 322 | 323 | 10. Versions of the License 324 | --------------------------- 325 | 326 | 10.1. New Versions 327 | 328 | Mozilla Foundation is the license steward. Except as provided in Section 329 | 10.3, no one other than the license steward has the right to modify or 330 | publish new versions of this License. Each version will be given a 331 | distinguishing version number. 332 | 333 | 10.2. Effect of New Versions 334 | 335 | You may distribute the Covered Software under the terms of the version 336 | of the License under which You originally received the Covered Software, 337 | or under the terms of any subsequent version published by the license 338 | steward. 339 | 340 | 10.3. Modified Versions 341 | 342 | If you create software not governed by this License, and you want to 343 | create a new license for such software, you may create and use a 344 | modified version of this License if you rename the license and remove 345 | any references to the name of the license steward (except to note that 346 | such modified license differs from this License). 347 | 348 | 10.4. Distributing Source Code Form that is Incompatible With Secondary 349 | Licenses 350 | 351 | If You choose to distribute Source Code Form that is Incompatible With 352 | Secondary Licenses under the terms of this version of the License, the 353 | notice described in Exhibit B of this License must be attached. 354 | 355 | Exhibit A - Source Code Form License Notice 356 | ------------------------------------------- 357 | 358 | This Source Code Form is subject to the terms of the Mozilla Public 359 | License, v. 2.0. If a copy of the MPL was not distributed with this 360 | file, You can obtain one at https://mozilla.org/MPL/2.0/. 361 | 362 | If it is not possible or desirable to put the notice in a particular 363 | file, then You may include the notice in a location (such as a LICENSE 364 | file in a relevant directory) where a recipient would be likely to look 365 | for such a notice. 366 | 367 | You may add additional accurate notices of copyright ownership. 368 | 369 | Exhibit B - "Incompatible With Secondary Licenses" Notice 370 | --------------------------------------------------------- 371 | 372 | This Source Code Form is "Incompatible With Secondary Licenses", as 373 | defined by the Mozilla Public License, v. 2.0. 374 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |

2 |

docr | doc-cr | /ˈdɒ·kur/

3 |

A CLI tool for searching Crystal documentation

4 |

5 | 6 | ## Installation 7 | 8 | See the [releases page](https://github.com/devnote-dev/docr/releases/latest) for available binaries. 9 | 10 | ### Windows 11 | 12 | ``` 13 | scoop bucket add docr https://github.com/devnote-dev/docr 14 | scoop install docr 15 | ``` 16 | 17 | ### From Source 18 | 19 | Crystal v1.10.0 or above is required to build Docr. 20 | 21 | ```sh 22 | git clone https://github.com/devnote-dev/docr 23 | cd docr 24 | shards build 25 | ``` 26 | 27 | ## Usage 28 | 29 | By default Docr comes with no libraries, but you can easily import the standard library documentation using `docr add crystal`. Docr will default to the latest available version, but you can specify the version as a second argument. You can also import shard documentation by specifying the source URL in one of the following formats: 30 | 31 | - docr add https://github.com/user/repo 32 | - docr add github.com/user/repo 33 | - docr add github:user/repo 34 | - docr add gh:user/repo 35 | 36 | The following shorthands are supported for sources: 37 | 38 | - github: / gh: 39 | - gitlab: / gl: 40 | - bitbucket: / bb: 41 | - codeberg: / cb: 42 | - srht: 43 | 44 | > [!IMPORTANT] 45 | > Only GitHub, GitLab, BitBucket, Codeberg and Source Hut are supported sources. Bare repositories are not supported. 46 | 47 | After importing the libraries you want, you can simply lookup or search whatever you want! Use the `docr search` command to search for all types and symbols matching the query, and the `docr info` command to get direct information about a specified type or symbol: 48 | 49 | ![demo_4](/assets/demo_4.png) 50 | 51 | Both the `info` and `search` commands support Crystal path syntax for queries, meaning the following commands are valid: 52 | 53 | - `docr info raise` 54 | - `docr info ::puts` 55 | - `docr info JSON.parse` 56 | - `docr info ::JSON::Any#as_s` 57 | 58 | However, the following commands _are not_ valid: 59 | 60 | - `docr info to_s.nil?` 61 | - `docr info IO.Memory` 62 | - `docr info JSON::parse` 63 | - `docr info JSON#Any.as_s` 64 | 65 | TODO: complete 'info' & 'search' headers 66 | 67 | ## Contributing 68 | 69 | 1. Fork it (https://github.com/devnote-dev/docr/fork) 70 | 2. Create your feature branch (`git checkout -b my-new-feature`) 71 | 3. Commit your changes (`git commit -am 'Add some feature'`) 72 | 4. Push to the branch (`git push origin my-new-feature`) 73 | 5. Create a new Pull Request 74 | 75 | ## Contributors 76 | 77 | - [Devonte](https://github.com/devnote-dev) - creator and maintainer 78 | 79 | This repository is managed under the Mozilla Public License v2. 80 | 81 | © 2023-present devnote-dev 82 | -------------------------------------------------------------------------------- /assets/demo_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/devnote-dev/docr/f6de13580c6356ccd820e61282eac7f1b43cb4ee/assets/demo_1.png -------------------------------------------------------------------------------- /assets/demo_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/devnote-dev/docr/f6de13580c6356ccd820e61282eac7f1b43cb4ee/assets/demo_2.png -------------------------------------------------------------------------------- /assets/demo_3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/devnote-dev/docr/f6de13580c6356ccd820e61282eac7f1b43cb4ee/assets/demo_3.png -------------------------------------------------------------------------------- /assets/demo_4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/devnote-dev/docr/f6de13580c6356ccd820e61282eac7f1b43cb4ee/assets/demo_4.png -------------------------------------------------------------------------------- /bucket/docr.json: -------------------------------------------------------------------------------- 1 | { 2 | "version": "1.0.0-nightly", 3 | "description": "A CLI tool for searching Crystal documentation", 4 | "homepage": "https://github.com/devnote-dev/docr#readme", 5 | "license": { 6 | "identifier": "MPL-2.0", 7 | "url": "https://github.com/devnote-dev/docr/blob/main/LICENSE" 8 | }, 9 | "url": [ 10 | "https://github.com/devnote-dev/docr/releases/download/nightly/docr-1.0.0-nightly-windows-x86_64-msvc.zip" 11 | ], 12 | "bin": [ 13 | "docr.exe", 14 | "docr.pdb" 15 | ] 16 | } -------------------------------------------------------------------------------- /shard.lock: -------------------------------------------------------------------------------- 1 | version: 2.0 2 | shards: 3 | baked_file_system: 4 | git: https://github.com/ralsina/baked_file_system.git 5 | version: 0.10.0+git.commit.beb373124c7a235cfb9cd94e36849d8168eaa04b 6 | 7 | base58: 8 | git: https://github.com/crystal-china/base58.cr.git 9 | version: 0.1.0+git.commit.2b0564a975171f4507c33251e0c0ab7990459e23 10 | 11 | cling: 12 | git: https://github.com/devnote-dev/cling.git 13 | version: 3.0.0+git.commit.3cd8b0baebb4b887b48a374f7e3f0887699fa4e5 14 | 15 | crest: 16 | git: https://github.com/mamantoha/crest.git 17 | version: 1.4.1 18 | 19 | docopt: 20 | git: https://github.com/chenkovsky/docopt.cr.git 21 | version: 0.2.0+git.commit.620fce4f334ff15d7321e5ecb6665ad258fe9297 22 | 23 | fzy: 24 | git: https://github.com/hugopl/fzy.git 25 | version: 0.5.5 26 | 27 | http-client-digest_auth: 28 | git: https://github.com/mamantoha/http-client-digest_auth.git 29 | version: 0.6.0 30 | 31 | http_proxy: 32 | git: https://github.com/mamantoha/http_proxy.git 33 | version: 0.12.0 34 | 35 | markd: 36 | git: https://github.com/icyleaf/markd.git 37 | version: 0.5.0 38 | 39 | pcf-parser: 40 | git: https://github.com/l3kn/pcf-parser.git 41 | version: 0.1.1 42 | 43 | redoc: 44 | git: https://github.com/devnote-dev/redoc.git 45 | version: 0.1.0+git.commit.7160bfdcbebd96c56448a68ff27c5fdf0e2f3226 46 | 47 | sixteen: 48 | git: https://github.com/ralsina/sixteen.git 49 | version: 0.4.2 50 | 51 | stumpy_core: 52 | git: https://github.com/stumpycr/stumpy_core.git 53 | version: 1.9.1 54 | 55 | stumpy_png: 56 | git: https://github.com/stumpycr/stumpy_png.git 57 | version: 5.0.1 58 | 59 | stumpy_utils: 60 | git: https://github.com/stumpycr/stumpy_utils.git 61 | version: 0.5.1 62 | 63 | tartrazine: 64 | git: https://github.com/ralsina/tartrazine.git 65 | version: 0.11.1 66 | 67 | -------------------------------------------------------------------------------- /shard.yml: -------------------------------------------------------------------------------- 1 | name: docr 2 | description: A CLI tool for searching Crystal documentation 3 | authors: 4 | - Devaune Whittle 5 | 6 | version: 1.0.0-beta 7 | crystal: '>= 1.10.0' 8 | license: MPL 9 | repository: https://github.com/devnote-dev/docr 10 | 11 | dependencies: 12 | cling: 13 | github: devnote-dev/cling 14 | branch: main 15 | 16 | crest: 17 | github: mamantoha/crest 18 | 19 | fzy: 20 | github: hugopl/fzy 21 | 22 | markd: 23 | github: icyleaf/markd 24 | 25 | redoc: 26 | github: devnote-dev/redoc 27 | branch: main 28 | 29 | tartrazine: 30 | github: ralsina/tartrazine 31 | 32 | scripts: 33 | build@windows: | 34 | set TT_THEMES=github-dark 35 | crystal build src\main.cr -Dtzcolors -Dnolexers -Dnothemes -o bin\docr 36 | 37 | build@linux: | 38 | TT_THEMES=github-dark 39 | crystal build src/main.cr -Dtzcolors -Dnolexers -Dnothemes -o bin/docr 40 | 41 | targets: 42 | docr: 43 | main: src/main.cr 44 | flags: --stats 45 | -------------------------------------------------------------------------------- /src/commands/about.cr: -------------------------------------------------------------------------------- 1 | module Docr::Commands 2 | class About < Base 3 | def setup : Nil 4 | @name = "about" 5 | @summary = "gets information about a library" 6 | @description = <<-DESC 7 | Gets information about a specified library. This will use the body text from the 8 | Crystal docs tool which is generally the README.md file of the library. 9 | DESC 10 | 11 | add_usage "docr about [version]" 12 | 13 | add_argument "name", description: "the name of the library", required: true 14 | add_argument "version", description: "the version of the library (defaults to latest)" 15 | end 16 | 17 | def run(arguments : Cling::Arguments, options : Cling::Options) : Nil 18 | name = arguments.get("name").as_s 19 | version = arguments.get?("version").try &.as_s 20 | 21 | unless Library.exists?(name, version) 22 | if version 23 | if Library.exists?(name) 24 | error "Version '#{version}' of #{name} not found or imported" 25 | exit_program 26 | end 27 | end 28 | 29 | error "Library '#{name}' not imported" 30 | exit_program 31 | end 32 | 33 | version ||= Library.get_versions_for(name).last 34 | library = Library.get name, version 35 | doc = Markd::Parser.parse library.description 36 | 37 | stdout.puts Renderer.new.render(doc) 38 | rescue JSON::Error 39 | error "Failed to open library: source file is in an invalid format" 40 | error "Please remove and import the library again" 41 | end 42 | end 43 | end 44 | -------------------------------------------------------------------------------- /src/commands/add.cr: -------------------------------------------------------------------------------- 1 | module Docr::Commands 2 | class Add < Base 3 | KNOWN_SOURCES = { 4 | "github.com", 5 | "gitlab.com", 6 | "bitbucket.com", 7 | "codeberg.org", 8 | "sr.ht", 9 | "git.sr.ht", 10 | } 11 | 12 | def setup : Nil 13 | @name = "add" 14 | @summary = "imports documentation for a library" 15 | @description = <<-DESC 16 | Imports a version of a specified library (or shard). By default the latest 17 | version is installed, this can be changed by specifying the version as the 18 | second argument. To import Crystal's standard library, specify 'crystal'. For 19 | all other libraries, the following formats are supported for the source: 20 | 21 | - docr add https://github.com/user/repo 22 | - docr add github.com/user/repo 23 | - docr add github:user/repo 24 | - docr add gh:user/repo 25 | 26 | The following shorthands are supported for sources: 27 | - github: / gh: 28 | - gitlab: / gl: 29 | - bitbucket: / bb: 30 | - codeberg: / cb: 31 | - srht: 32 | 33 | Absolute URLs to sources other than GitHub, GitLab, BitBucket, Codeberg and 34 | Source Hut are not yet supported. 35 | DESC 36 | 37 | add_usage "docr add [version] [-a|--alias ]" 38 | add_usage "docr add crystal [version]" 39 | 40 | add_argument "source", description: "the source of the library (or 'crystal')", required: true 41 | add_argument "version", description: "the version to install (defaults to latest)" 42 | add_option 'a', "alias", type: :single 43 | end 44 | 45 | def run(arguments : Cling::Arguments, options : Cling::Options) : Nil 46 | source = arguments.get("source").as_s 47 | 48 | if source == "crystal" 49 | add_crystal_library arguments.get?("version").try(&.as_s) 50 | else 51 | add_external_library( 52 | source, 53 | arguments.get?("version").try(&.as_s), 54 | options.get?("alias").try(&.as_s) 55 | ) 56 | end 57 | end 58 | 59 | private def add_crystal_library(version : String?) : Nil 60 | info "Fetching available versions..." 61 | 62 | versions = fetch_versions_for( 63 | "crystal", 64 | "https://crystal-lang.org/api/versions.json", 65 | version 66 | ) 67 | version = versions[1] if version.nil? 68 | term = version == "nightly" ? "nightly build" : "version #{version}" 69 | set = Library.get_versions_for "crystal" 70 | 71 | if version != "nightly" && set.includes? version 72 | error "Crystal #{term} is already imported" 73 | exit_program 74 | end 75 | 76 | unless versions.includes? version 77 | error "Crystal #{term} is not available" 78 | error "Run '#{"docr check".colorize.blue}' to see available versions of imported libraries" 79 | exit_program 80 | end 81 | 82 | info "Importing library..." 83 | 84 | File.open(LIBRARY_DIR / "crystal" / (version + ".json"), mode: "w") do |file| 85 | version = "master" if version == "nightly" 86 | Crest.get "https://crystal-lang.org/api/#{version}/index.json" do |res| 87 | library = Redoc.load res.body_io 88 | library.to_json file 89 | end 90 | end 91 | 92 | unless File.exists?(LIBRARY_DIR / "crystal" / "SOURCE") 93 | File.write(LIBRARY_DIR / "crystal" / "SOURCE", "https://crystal-lang.org/api") 94 | end 95 | 96 | info "Imported crystal #{term}" 97 | end 98 | 99 | private def add_external_library(source : String, version : String?, alias_name : String?) : Nil 100 | info "Resolving source..." 101 | 102 | case source 103 | when .starts_with?("github:"), .starts_with?("gh:") 104 | host = "github" 105 | path = source.gsub(/github:|gh:/, "") 106 | when .starts_with?("gitlab:"), .starts_with?("gl:") 107 | host = "gitlab" 108 | path = source.gsub(/gitlab:|gl:/, "") 109 | when .starts_with?("bitbucket:"), .starts_with?("bb:") 110 | host = "bitbucket" 111 | path = source.gsub(/bitbucket:|bb:/, "") 112 | when .starts_with?("codeberg:"), .starts_with?("cb:") 113 | host = "codeberg-org" 114 | path = source.gsub(/codeberg:|cb:/, "") 115 | when .starts_with?("srht:") 116 | host = "git-sr-ht" 117 | path = source.gsub("srht:", "") 118 | path = '~' + path unless path.starts_with? '~' 119 | else 120 | source = URI.parse source 121 | 122 | unless source.host.in? KNOWN_SOURCES 123 | error "Unsupported library source" 124 | error "See '#{"docr add --help".colorize.blue}' for more information" 125 | exit_program 126 | end 127 | 128 | host = source.host.as(String) 129 | if host == "sr.ht" || host == "git.sr.ht" 130 | host = "git-sr-ht" 131 | elsif host == "codeberg.org" 132 | host = "codeberg-org" 133 | else 134 | host = host.chomp ".com" 135 | end 136 | path = source.path.lchop '/' 137 | end 138 | 139 | path = path.chomp ".git" 140 | info "Fetching available versions..." 141 | base_url = "https://crystaldoc.info/#{host}/#{path}" 142 | debug url = "#{base_url}/versions.json" 143 | 144 | begin 145 | Crest.head url 146 | rescue Crest::NotFound 147 | error "Library not found" 148 | exit_program 149 | end 150 | 151 | name = alias_name || path.split('/')[1] 152 | versions = fetch_versions_for(name, url, version) 153 | 154 | if version.nil? 155 | version = versions[1] 156 | elsif !versions.includes?(version) 157 | error "Version #{version} not found for #{name}" 158 | error "Run '#{"docr check".colorize.blue}' to see available versions of imported libraries" 159 | exit_program 160 | end 161 | 162 | if Library.exists?(name) 163 | unless Library.get_source(name) == base_url 164 | error "Library #{name} has separate sources with the same name" 165 | error "Install this library using an '#{"--alias".colorize.blue}' or remove the existing library" 166 | exit_program 167 | end 168 | 169 | if Library.exists?(name, version) 170 | error "Library #{name} version #{version} is already imported" 171 | exit_program 172 | end 173 | end 174 | 175 | info "Importing library..." 176 | debug lib_dir = LIBRARY_DIR / name 177 | debug url = "#{base_url}/#{version}/index.json" 178 | 179 | begin 180 | Crest.get url do |res| 181 | File.open(lib_dir / "#{version}.json", mode: "w") do |dest| 182 | library = Redoc.load res.body_io.gets_to_end 183 | library.to_json dest 184 | end 185 | end 186 | File.write(lib_dir / "SOURCE", "https://crystaldoc.info/#{host}/#{path}") 187 | 188 | info "Imported #{name} version #{version}" 189 | rescue ex 190 | error "Failed to save library data:" 191 | error ex.to_s 192 | end 193 | end 194 | 195 | private def fetch_versions_for(name : String, url : String, req : String?) : Array(String) 196 | path = LIBRARY_DIR / name / "VERSIONS" 197 | 198 | if req && File.exists? path 199 | versions = File.read_lines path 200 | return versions if versions.includes? req 201 | else 202 | Dir.mkdir_p LIBRARY_DIR / name 203 | end 204 | 205 | res = Crest.get url 206 | versions = Array({name: String}) 207 | .from_json(res.body, root: "versions") 208 | .map(&.[:name]) 209 | 210 | File.write(path, versions.join('\n')) 211 | 212 | versions 213 | end 214 | end 215 | end 216 | -------------------------------------------------------------------------------- /src/commands/base.cr: -------------------------------------------------------------------------------- 1 | module Docr::Commands 2 | abstract class Base < Cling::Command 3 | def initialize 4 | super 5 | 6 | @inherit_options = true 7 | @debug = false 8 | add_option "debug", description: "print debug information" 9 | add_option "no-color", description: "disable ansi color codes" 10 | add_option 'h', "help", description: "get help information" 11 | end 12 | 13 | def help_template : String 14 | String.build do |io| 15 | io << "Usage".colorize.blue << '\n' 16 | @usage.each do |use| 17 | io << "• " << use << '\n' 18 | end 19 | io << '\n' 20 | 21 | unless @children.empty? 22 | io << "Commands".colorize.blue << '\n' 23 | max_size = 4 + @children.keys.max_of &.size 24 | 25 | @children.each do |name, command| 26 | io << "• " << name.colorize.bold 27 | if summary = command.summary 28 | io << " " * (max_size - name.size) 29 | io << summary 30 | end 31 | io << '\n' 32 | end 33 | 34 | io << '\n' 35 | end 36 | 37 | io << "Options".colorize.blue << '\n' 38 | max_size = 4 + @options.each.max_of { |name, opt| name.size + (opt.short ? 2 : 0) } 39 | 40 | @options.each do |name, option| 41 | if short = option.short 42 | io << '-' << short << ", " 43 | end 44 | io << "--" << name 45 | 46 | if description = option.description 47 | name_size = name.size + (option.short ? 4 : 0) 48 | io << " " * (max_size - name_size) 49 | io << description 50 | end 51 | io << '\n' 52 | end 53 | io << '\n' 54 | 55 | io << "Description".colorize.blue << '\n' 56 | io << @description 57 | end 58 | end 59 | 60 | def pre_run(arguments : Cling::Arguments, options : Cling::Options) : Nil 61 | @debug = true if options.has? "debug" 62 | Colorize.enabled = false if options.has? "no-color" 63 | 64 | if options.has? "help" 65 | stdout.puts help_template 66 | exit_program 0 67 | end 68 | end 69 | 70 | def debug(data : _) : Nil 71 | return unless @debug 72 | stdout << "(#) ".colorize.bold << data << '\n' 73 | end 74 | 75 | def info(data : _) : Nil 76 | stdout << "(i) ".colorize.blue << data << '\n' 77 | end 78 | 79 | def warn(data : _) : Nil 80 | stdout << "(!) ".colorize.yellow << data << '\n' 81 | end 82 | 83 | def error(data : _) : Nil 84 | stdout << "(!) ".colorize.red << data << '\n' 85 | end 86 | 87 | def on_error(ex : Exception) 88 | case ex 89 | when Cling::CommandError 90 | error ex 91 | error "See '#{"docr --help".colorize.blue}' for more information" 92 | when Redoc::Error 93 | error ex 94 | # TODO: "See 'docr help query' for more information" 95 | else 96 | error "Unexpected exception:" 97 | error ex 98 | error "Please report this on the Docr GitHub issues:" 99 | error "https://github.com/devnote-dev/docr/issues" 100 | end 101 | 102 | if @debug 103 | debug "loading stack trace..." 104 | 105 | stack = ex.backtrace || %w[???] 106 | stack.each { |line| debug " " + line } 107 | end 108 | 109 | exit_program 110 | end 111 | 112 | def on_missing_arguments(args : Array(String)) 113 | command = "docr #{self.name} --help".colorize.blue 114 | error "Missing required argument#{"s" if args.size > 1}:" 115 | error " #{args.join(", ")}" 116 | error "See '#{command}' for more information" 117 | exit_program 118 | end 119 | 120 | def on_unknown_arguments(args : Array(String)) 121 | command = %(docr #{self.name == "main" ? "" : self.name + " "}--help).colorize.blue 122 | error "Unexpected argument#{"s" if args.size > 1} for this command:" 123 | error " #{args.join ", "}" 124 | error "See '#{command}' for more information" 125 | exit_program 126 | end 127 | 128 | def on_unknown_options(options : Array(String)) 129 | command = %(docr #{self.name == "main" ? "" : self.name + " "}--help).colorize.blue 130 | error "Unexpected option#{"s" if options.size > 1} for this command:" 131 | error " #{options.join ", "}" 132 | error "See '#{command}' for more information" 133 | exit_program 134 | end 135 | end 136 | end 137 | -------------------------------------------------------------------------------- /src/commands/check.cr: -------------------------------------------------------------------------------- 1 | module Docr::Commands 2 | class Check < Base 3 | def setup : Nil 4 | @name = "check" 5 | 6 | add_argument "library" 7 | end 8 | 9 | def run(arguments : Cling::Arguments, options : Cling::Options) : Nil 10 | if name = arguments.get?("library").try &.as_s 11 | if Library.exists?(name) 12 | check name, Library.get_versions_for(name) 13 | else 14 | error "Library '#{name}' not imported" 15 | exit_program 16 | end 17 | else 18 | Library.list_all.each do |name, versions| # ameba:disable Lint/ShadowingOuterLocalVar 19 | stdout.puts name 20 | check name, versions 21 | stdout.puts 22 | end 23 | end 24 | end 25 | 26 | private def check(name : String, installed : Array(String)) : Nil 27 | url = Library.get_source name 28 | res = Crest.get url + "/versions.json" 29 | max = SemanticVersion.new(10, 0, 0) 30 | 31 | Array({name: String}) 32 | .from_json(res.body, root: "versions") 33 | .map(&.[:name]) 34 | .reject(&.in? installed) 35 | .map { |v| {v, false} } 36 | .concat(installed.map { |v| {v, true} }) 37 | .sort_by! { |(v, _)| SemanticVersion.parse(v) rescue max } 38 | .reverse_each do |(name, added)| 39 | if added 40 | Colorize.with.green.surround(stdout) do 41 | stdout << "• [x] " << name << '\n' 42 | end 43 | else 44 | stdout << "• [ ] " << name << '\n' 45 | end 46 | end 47 | end 48 | end 49 | end 50 | -------------------------------------------------------------------------------- /src/commands/help.cr: -------------------------------------------------------------------------------- 1 | module Docr::Commands 2 | class Help < Base 3 | def setup : Nil 4 | @name = "help" 5 | @summary = "get help information for a command" 6 | 7 | add_argument "command" 8 | end 9 | 10 | def pre_run(arguments : Cling::Arguments, options : Cling::Options) : Nil 11 | Colorize.enabled = false if options.has? "no-color" 12 | end 13 | 14 | def run(arguments : Cling::Arguments, options : Cling::Options) : Nil 15 | main = parent.as(Cling::Command) 16 | command = arguments.get?("command").try &.as_s 17 | 18 | if command && command != "help" 19 | main.execute [command, "--help"] 20 | else 21 | main.run arguments, options 22 | end 23 | end 24 | end 25 | end 26 | -------------------------------------------------------------------------------- /src/commands/info.cr: -------------------------------------------------------------------------------- 1 | module Docr::Commands 2 | class Info < Base 3 | def setup : Nil 4 | @name = "info" 5 | @summary = "gets information about a symbol" 6 | @description = <<-DESC 7 | Gets information about a specified type/namespace or symbol. This uses 8 | Crystal path syntax, meaning the following commands are valid: 9 | 10 | • docr info raise 11 | • docr info ::puts 12 | • docr info JSON.parse 13 | • docr info ::JSON::Any#as_s 14 | 15 | However, the following commands are not valid: 16 | 17 | • docr info to_s.nil? 18 | • docr info IO.Memory 19 | • docr info JSON::parse 20 | • docr info JSON#Any.as_s 21 | 22 | Type namespaces are separated by '::', class methods are denoted by '.' 23 | and instance methods are denoted by '#'. The type lookup order starts 24 | at the top-level and recurses down the type path. 25 | DESC 26 | 27 | add_argument "query", required: true 28 | add_option 'l', "library", type: :single, default: "crystal" 29 | add_option 'p', "open-page" 30 | add_option 's', "open-source" 31 | add_option 'r', "result", type: :single, default: 1 32 | add_option 'v', "version", type: :single 33 | end 34 | 35 | def pre_run(arguments : Cling::Arguments, options : Cling::Options) : Nil 36 | if result = options.get("result").to_i32? 37 | if result < 1 38 | error "Result integer cannot be less than 1" 39 | exit_program 40 | end 41 | else 42 | error "Invalid integer for result option" 43 | exit_program 44 | end 45 | end 46 | 47 | def run(arguments : Cling::Arguments, options : Cling::Options) : Nil 48 | name = options.get("library").as_s 49 | version = options.get?("version").try &.as_s 50 | 51 | unless Library.exists?(name, version) 52 | if version 53 | if Library.exists?(name) 54 | error "Version '#{version}' of #{name} not found or imported" 55 | exit_program 56 | end 57 | end 58 | 59 | error "Library '#{name}' not imported" 60 | exit_program 61 | end 62 | 63 | version ||= Library.get_versions_for(name).last 64 | library = Library.get name, version 65 | namespace, symbol, scope = Redoc.parse_query arguments.get("query").as_s 66 | 67 | if symbol 68 | types = library.resolve_all namespace, symbol, scope 69 | if types.empty? && namespace.empty? && name == "crystal" 70 | namespace << "Object" 71 | types = library.resolve_all namespace, symbol, scope 72 | end 73 | 74 | if types.empty? 75 | error "Could not resolve types or symbols for input" 76 | exit_program 77 | end 78 | 79 | result_index = options.get("result").to_i32 80 | max_types = types.size 81 | 82 | if result_index > max_types 83 | error "Result index out of range (#{result_index}/#{max_types})" 84 | exit_program 85 | end 86 | 87 | type = types[result_index - 1] 88 | 89 | unless max_types == 1 90 | stdout << max_types << " results found " 91 | stdout << "(select using '--result')\n\n".colorize.dark_gray 92 | end 93 | else 94 | unless type = library.resolve? namespace, symbol, scope 95 | if namespace.empty? && name == "crystal" 96 | namespace << "Object" 97 | type = library.resolve? namespace, symbol, scope 98 | end 99 | end 100 | 101 | unless type 102 | error "Could not resolve types or symbols for input" 103 | exit_program 104 | end 105 | end 106 | 107 | if options.has? "open-page" 108 | if name == "crystal" 109 | uri = URI.parse "https://crystal-lang.org/api/#{version}/" 110 | else 111 | uri = URI.parse Library.get_source(name) + "/#{version}/" 112 | end 113 | 114 | build_page_uri(uri, type) 115 | elsif options.has? "open-source" 116 | uri = build_source_uri type 117 | else 118 | return Formatters::Default.info stdout, type 119 | end 120 | 121 | uri = uri.to_s 122 | 123 | {% if flag?(:win32) %} 124 | Process.run "cmd /c start #{uri}", shell: true 125 | {% elsif flag?(:macos) %} 126 | Process.run "open", [uri], shell: true 127 | {% else %} 128 | {"xdg-open", "sensible-browser", "firefox", "google-chrome"}.each do |command| 129 | return if Process.run(command, [uri], shell: true).success? 130 | end 131 | 132 | error "Could not find a program to open URI:" 133 | error uri 134 | exit_program 135 | {% end %} 136 | end 137 | 138 | private def build_page_uri(uri : URI, type : Redoc::Type) : Nil 139 | case type 140 | in Redoc::Namespace, Redoc::Enum, Redoc::Alias, Redoc::Annotation 141 | uri.path += type.path 142 | in Redoc::Def, Redoc::Macro 143 | if ref_path = type.parent.try &.path 144 | uri.path += ref_path 145 | else 146 | uri.path += "toplevel.html" 147 | end 148 | uri.fragment = type.html_id 149 | in Redoc::Const 150 | if ref_path = type.parent.try &.path 151 | uri.path += ref_path 152 | uri.fragment = type.name 153 | elsif type.top_level? 154 | uri.path += "toplevel.html" 155 | uri.fragment = type.name 156 | else 157 | error "Could not resolve a location for constant type" 158 | exit_program 159 | end 160 | in Redoc::Type 161 | raise "unreachable" 162 | end 163 | end 164 | 165 | private def build_source_uri(type : Redoc::Type) : URI 166 | if type.responds_to?(:locations) 167 | url = type.locations[0].url 168 | elsif type.responds_to?(:location) 169 | url = type.location.try &.url 170 | end 171 | 172 | unless url 173 | error "Could not resolve a location for type" 174 | exit_program 175 | end 176 | 177 | URI.parse url 178 | end 179 | end 180 | end 181 | -------------------------------------------------------------------------------- /src/commands/list.cr: -------------------------------------------------------------------------------- 1 | module Docr::Commands 2 | class List < Base 3 | def setup : Nil 4 | @name = "list" 5 | @summary = "lists imported libraries" 6 | @description = "Lists imported libraries, including their versions." 7 | end 8 | 9 | def run(arguments : Cling::Arguments, options : Cling::Options) : Nil 10 | stdout << String.build do |io| 11 | libs = Library.list_all 12 | if libs.empty? 13 | error "No libraries have been installed" 14 | exit_program 15 | end 16 | 17 | libs.each do |name, versions| 18 | io << name << '\n' 19 | versions.reverse_each do |version| 20 | io << "• " 21 | io << 'v' if version[0].ascii_number? 22 | io << version << '\n' 23 | end 24 | io << '\n' 25 | end 26 | end.chomp 27 | end 28 | end 29 | end 30 | -------------------------------------------------------------------------------- /src/commands/remove.cr: -------------------------------------------------------------------------------- 1 | module Docr::Commands 2 | class Remove < Base 3 | def setup : Nil 4 | @name = "remove" 5 | @summary = "removes a library" 6 | @description = "Removes an imported library. If the 'version' argument is not specified, all\n" \ 7 | "versions of the library are removed." 8 | 9 | add_usage "docr remove [version]" 10 | 11 | add_argument "name", description: "the name of the library", required: true 12 | add_argument "version", description: "the version of the library" 13 | end 14 | 15 | def run(arguments : Cling::Arguments, options : Cling::Options) : Nil 16 | name = arguments.get("name").as_s 17 | version = arguments.get?("version").try &.as_s 18 | 19 | unless Library.exists?(name, version) 20 | if version 21 | if Library.exists?(name) 22 | error "Version '#{version}' of #{name} not found or imported" 23 | exit_program 24 | end 25 | end 26 | 27 | error "Library '#{name}' not imported" 28 | exit_program 29 | end 30 | 31 | Library.delete name, version 32 | end 33 | end 34 | end 35 | -------------------------------------------------------------------------------- /src/commands/search.cr: -------------------------------------------------------------------------------- 1 | module Docr::Commands 2 | class Search < Base 3 | def setup : Nil 4 | @name = "search" 5 | @summary = "search for a symbol or type" 6 | 7 | add_argument "query", required: true 8 | add_option 'l', "library", type: :single, default: "crystal" 9 | add_option 'v', "version", type: :single 10 | end 11 | 12 | def run(arguments : Cling::Arguments, options : Cling::Options) : Nil 13 | name = options.get("library").as_s 14 | version = options.get?("version").try &.as_s 15 | 16 | unless Library.exists?(name, version) 17 | if version 18 | if Library.exists?(name) 19 | error "Version '#{version}' of #{name} not found or imported" 20 | exit_program 21 | end 22 | end 23 | 24 | error "Library '#{name}' not imported" 25 | exit_program 26 | end 27 | 28 | version ||= Library.get_versions_for(name).last 29 | library = Library.get name, version 30 | input = arguments.get("query").as_s 31 | query = Redoc.parse_query input 32 | namespace, symbol, scope = query 33 | types = [] of {Float32, Redoc::Type} 34 | 35 | unless namespace.empty? 36 | full_name = namespace.join "::" 37 | 38 | {% for type in %w[modules classes structs enums aliases annotations] %} 39 | Fzy.search(full_name, library.{{type.id}}.map &.full_name).each do |match| 40 | types << {match.score, library.{{type.id}}[match.index]} 41 | end 42 | {% end %} 43 | 44 | {% for type in %w[modules classes structs] %} 45 | library.{{type.id}}.each do |type| 46 | recurse_types full_name, types, type 47 | end 48 | {% end %} 49 | end 50 | 51 | if symbol 52 | if namespace.empty? 53 | {% for type in %w[methods macros] %} 54 | Fzy.search(symbol, library.{{type.id}}.map &.name).each do |match| 55 | types << {match.score, library.{{type.id}}[match.index]} 56 | end 57 | {% end %} 58 | 59 | {% for type in %w[modules classes structs] %} 60 | library.{{type.id}}.each do |type| 61 | recurse_methods symbol, types, type, :all 62 | end 63 | {% end %} 64 | else 65 | types.each_with_index do |type, index| 66 | methods = [] of {Float32, Redoc::Type} 67 | 68 | if scope.class? 69 | if type.responds_to?(:constructors) 70 | Fzy.search(symbol, type.constructors.map &.name).each do |match| 71 | methods << {match.score, type.constructors[match.index]} 72 | end 73 | end 74 | 75 | if type.responds_to?(:class_methods) 76 | Fzy.search(symbol, type.class_methods.map &.name).each do |match| 77 | methods << {match.score, type.class_methods[match.index]} 78 | end 79 | end 80 | else 81 | if type.responds_to?(:instance_methods) 82 | Fzy.search(symbol, type.instance_methods.map &.name).each do |match| 83 | methods << {match.score, type.instance_methods[match.index]} 84 | end 85 | end 86 | end 87 | 88 | unless methods.empty? 89 | types.insert_all index + 1, methods 90 | end 91 | types.delete_at index 92 | end 93 | end 94 | end 95 | 96 | if types.empty? 97 | error "Could not resolve types or symbols for input" 98 | exit_program 99 | end 100 | 101 | types.sort_by! do |(score, type)| 102 | if type.responds_to?(:full_name) 103 | {score, type.full_name} 104 | else 105 | {score, type.name} 106 | end 107 | end 108 | 109 | stdout << types.size << " result" 110 | stdout << "s" if types.size > 1 111 | stdout << " found:\n\n" 112 | 113 | if options.has? "debug" 114 | types.reverse_each do |score, type| 115 | Colorize.with.dark_gray.surround(stdout) do 116 | stdout << '[' << score << "] " 117 | end 118 | Formatters::Default.signature stdout, type, true, false 119 | end 120 | else 121 | types.reverse_each do |_, type| 122 | Formatters::Default.signature stdout, type, true, false 123 | end 124 | end 125 | end 126 | 127 | private def recurse_types(query : String, results : Array({Float32, Redoc::Type}), 128 | namespace : Redoc::Namespace) : Nil 129 | {% for type in %w[modules classes structs enums aliases annotations] %} 130 | Fzy.search(query, namespace.{{type.id}}.map &.full_name).each do |match| 131 | next if match.score < 1.0 132 | results << {match.score, namespace.{{type.id}}[match.index]} 133 | end 134 | {% end %} 135 | 136 | {% for type in %w[modules classes structs] %} 137 | namespace.{{type.id}}.each do |type| 138 | recurse_types query, results, type 139 | end 140 | {% end %} 141 | end 142 | 143 | private def recurse_methods(query : String, results : Array({Float32, Redoc::Type}), 144 | namespace : Redoc::Namespace, scope : Redoc::QueryScope) : Nil 145 | if scope.all? || scope.class? 146 | if namespace.responds_to?(:constructors) 147 | Fzy.search(query, namespace.constructors.map &.name).each do |match| 148 | next if match.score < 2.0 149 | results << {match.score, namespace.constructors[match.index]} 150 | end 151 | end 152 | 153 | if namespace.responds_to?(:class_methods) 154 | Fzy.search(query, namespace.class_methods.map &.name).each do |match| 155 | next if match.score < 2.0 156 | results << {match.score, namespace.class_methods[match.index]} 157 | end 158 | end 159 | end 160 | 161 | if (scope.all? || scope.instance?) && namespace.responds_to?(:instance_methods) 162 | Fzy.search(query, namespace.instance_methods.map &.name).each do |match| 163 | next if match.score < 2.0 164 | results << {match.score, namespace.instance_methods[match.index]} 165 | end 166 | end 167 | 168 | {% for type in %w[modules classes structs] %} 169 | namespace.{{type.id}}.each do |type| 170 | recurse_methods query, results, type, scope 171 | end 172 | {% end %} 173 | end 174 | end 175 | end 176 | -------------------------------------------------------------------------------- /src/commands/tree.cr: -------------------------------------------------------------------------------- 1 | module Docr::Commands 2 | class Tree < Base 3 | private TYPES = %w[ 4 | const constants 5 | modules classes structs 6 | enums 7 | aliases 8 | anno annotations 9 | defs macros 10 | ] 11 | 12 | def setup : Nil 13 | @name = "tree" 14 | 15 | add_argument "query" 16 | add_option 'i', "include", type: :multiple 17 | add_option 'x', "exclude", type: :multiple 18 | add_option 'f', "format", type: :single 19 | add_option "location" 20 | add_option 'l', "library", type: :single, default: "crystal" 21 | add_option 'v', "version", type: :single 22 | end 23 | 24 | def pre_run(arguments : Cling::Arguments, options : Cling::Options) : Nil 25 | super 26 | 27 | if format = options.get?("format").try(&.as_s) 28 | unless format.in?("default", "signature") # TODO: impl json, csv 29 | error "Invalid format (valid: default, signature)" 30 | exit_program 31 | end 32 | end 33 | 34 | invalid = [] of String 35 | 36 | if includes = options.get?("include").try(&.as_a) 37 | invalid.concat includes.reject { |i| i.in?(TYPES) || i == "all" } 38 | end 39 | 40 | if excludes = options.get?("exclude").try(&.as_a) 41 | invalid.concat excludes.reject { |e| e.in?(TYPES) || e == "all" } 42 | end 43 | 44 | unless invalid.empty? 45 | warn "Ignoring unknown types:" 46 | warn " #{invalid.join(", ")}" 47 | end 48 | end 49 | 50 | def run(arguments : Cling::Arguments, options : Cling::Options) : Nil 51 | name = options.get("library").as_s 52 | version = options.get?("version").try &.as_s 53 | 54 | unless Library.exists?(name, version) 55 | if version 56 | if Library.exists?(name) 57 | error "Version '#{version}' of #{name} not found or imported" 58 | exit_program 59 | end 60 | end 61 | 62 | error "Library '#{name}' not imported" 63 | exit_program 64 | end 65 | 66 | version ||= Library.get_versions_for(name).last 67 | library = Library.get name, version 68 | types = TYPES.dup 69 | 70 | if excludes = options.get?("exclude").try(&.as_a) 71 | if excludes.includes? "all" 72 | types.clear 73 | else 74 | types.reject! &.in? excludes 75 | end 76 | end 77 | 78 | if includes = options.get?("include").try(&.as_a) 79 | if includes.includes? "all" 80 | types.replace TYPES 81 | else 82 | types.concat TYPES.select &.in? includes 83 | end 84 | end 85 | 86 | if arguments.has? "query" 87 | query = Redoc.parse_query arguments.get("query").as_s 88 | 89 | unless type = library.resolve? *query 90 | if query[0].empty? && name == "crystal" 91 | query[0] << "Object" 92 | type = library.resolve? *query 93 | end 94 | end 95 | 96 | unless type 97 | error "Could not resolve types or symbols for input" 98 | exit_program 99 | end 100 | else 101 | type = library 102 | end 103 | 104 | case options.get?("format").try(&.as_s) 105 | when Nil, "default" 106 | Formatters::Default.tree(stdout, type, types, options.has?("location")) 107 | when "signature" 108 | Formatters::Signature.format(stdout, type, types, options.has?("location")) 109 | end 110 | end 111 | end 112 | end 113 | -------------------------------------------------------------------------------- /src/commands/version.cr: -------------------------------------------------------------------------------- 1 | module Docr::Commands 2 | class Version < Base 3 | def setup : Nil 4 | @name = "version" 5 | @summary = "shows version information" 6 | @description = "Shows the version information for Docr." 7 | end 8 | 9 | def run(arguments : Cling::Arguments, options : Cling::Options) : Nil 10 | stdout << "docr version " << Docr::VERSION 11 | stdout << " [" << Docr::BUILD_HASH << "] (" 12 | stdout << Docr::BUILD_DATE << ")\n" 13 | end 14 | end 15 | end 16 | -------------------------------------------------------------------------------- /src/docr.cr: -------------------------------------------------------------------------------- 1 | require "cling" 2 | require "colorize" 3 | require "crest" 4 | require "file_utils" 5 | require "fzy" 6 | require "json" 7 | require "markd" 8 | require "redoc" 9 | {% if flag?(:tzcolors) %} 10 | require "tartrazine" 11 | {% end %} 12 | require "yaml" 13 | 14 | require "./commands/base" 15 | require "./commands/*" 16 | require "./formatters/**" 17 | require "./library" 18 | require "./renderer" 19 | 20 | Colorize.on_tty_only! 21 | 22 | module Docr 23 | VERSION = "1.0.0-beta" 24 | 25 | BUILD_DATE = {% if flag?(:win32) %} 26 | {{ `powershell.exe -NoProfile Get-Date -Format "yyyy-MM-dd"`.stringify.chomp }} 27 | {% else %} 28 | {{ `date +%F`.stringify.chomp }} 29 | {% end %} 30 | BUILD_HASH = {{ `git rev-parse HEAD`.stringify[0...8] }} 31 | 32 | LIBRARY_DIR = {% if flag?(:win32) %} 33 | Path[ENV["APPDATA"], "docr"] 34 | {% else %} 35 | Path[ENV["XDG_DATA_HOME"]? || Path.home / ".local" / "share" / "docr"] 36 | {% end %} 37 | 38 | class App < Commands::Base 39 | def setup : Nil 40 | @name = "main" 41 | @description = <<-DESC 42 | A CLI tool for searching Crystal documentation with version support 43 | for the standard library documentation and documentation for third-party 44 | libraries (or shards). 45 | DESC 46 | 47 | add_usage "docr [options] " 48 | 49 | add_command Commands::About.new 50 | add_command Commands::List.new 51 | add_command Commands::Check.new 52 | add_command Commands::Info.new 53 | add_command Commands::Search.new 54 | add_command Commands::Tree.new 55 | add_command Commands::Add.new 56 | add_command Commands::Remove.new 57 | add_command Commands::Help.new 58 | add_command Commands::Version.new 59 | end 60 | 61 | def run(arguments : Cling::Arguments, options : Cling::Options) : Nil 62 | stdout.puts help_template 63 | end 64 | end 65 | end 66 | -------------------------------------------------------------------------------- /src/formatters/base.cr: -------------------------------------------------------------------------------- 1 | module Docr::Formatters::Base 2 | protected getter? constants : Bool = false 3 | protected getter? modules : Bool = false 4 | protected getter? classes : Bool = false 5 | protected getter? structs : Bool = false 6 | protected getter? enums : Bool = false 7 | protected getter? aliases : Bool = false 8 | protected getter? annotations : Bool = false 9 | protected getter? defs : Bool = false 10 | protected getter? macros : Bool = false 11 | 12 | protected def apply(includes : Array(String)) : Nil 13 | @constants = includes.includes?("constants") || includes.includes?("const") 14 | @modules = includes.includes? "modules" 15 | @classes = includes.includes? "classes" 16 | @structs = includes.includes? "structs" 17 | @enums = includes.includes? "enums" 18 | @aliases = includes.includes? "aliases" 19 | @annotations = includes.includes?("annotations") || includes.includes?("anno") 20 | @defs = includes.includes? "defs" 21 | @macros = includes.includes? "macros" 22 | end 23 | end 24 | -------------------------------------------------------------------------------- /src/formatters/default/info.cr: -------------------------------------------------------------------------------- 1 | module Docr::Formatters 2 | class Default 3 | def self.info(io : IO, type : Redoc::Const) : Nil 4 | signature io, type, true, true 5 | 6 | if summary = type.summary 7 | io << "\n " << parse_markdown(summary) << '\n' 8 | end 9 | 10 | io << "\nDefined: " 11 | if type.top_level? 12 | io << "top-level namespace\n".colorize.dark_gray 13 | else 14 | io << "(cannot resolve location)\n".colorize.dark_gray 15 | end 16 | 17 | if doc = type.doc 18 | io << '\n' << parse_markdown(doc) << '\n' 19 | end 20 | end 21 | 22 | {% for type in %w[Module Class Struct Alias Annotation] %} 23 | def self.info(io : IO, type : Redoc::{{type.id}}) : Nil 24 | signature io, type, true, true 25 | info_base io, type 26 | end 27 | {% end %} 28 | 29 | def self.info(io : IO, type : Redoc::Enum) : Nil 30 | signature io, type, true, true 31 | 32 | type.constants.each do |const| 33 | io << " " << const.name.colorize.blue << " = " << const.value 34 | 35 | if summary = const.summary 36 | io << "\n " << parse_markdown(summary) << '\n' 37 | end 38 | 39 | io << '\n' 40 | end 41 | 42 | io << "end\n".colorize.red 43 | info_base io, type 44 | end 45 | 46 | {% for type in %w[Def Macro] %} 47 | def self.info(io : IO, type : Redoc::{{type.id}}) : Nil 48 | signature io, type, true, false 49 | 50 | if summary = type.summary 51 | io << "\n " << parse_markdown summary 52 | end 53 | 54 | io << "\nDefined:" 55 | if loc = type.location 56 | io << "\n• " << loc.filename << ':' << loc.line_number << '\n' 57 | if url = loc.url 58 | Colorize.with.dark_gray.surround(io) do 59 | io << " (" << url << ")\n" 60 | end 61 | end 62 | else 63 | io << " (cannot resolve location)\n".colorize.dark_gray 64 | end 65 | 66 | if doc = type.doc 67 | io << '\n' << parse_markdown(doc) << '\n' 68 | end 69 | end 70 | {% end %} 71 | 72 | private def self.info_base(io : IO, type : Redoc::Type) : Nil 73 | if summary = type.summary 74 | io << "\n " << parse_markdown summary 75 | end 76 | 77 | io << "\nDefined:\n" 78 | type.locations.each do |loc| 79 | io << "• " << loc.filename << ':' << loc.line_number << '\n' 80 | if url = loc.url 81 | Colorize.with.dark_gray.surround(io) do 82 | io << " (" << url << ")\n\n" 83 | end 84 | end 85 | end 86 | 87 | if doc = type.doc 88 | io << parse_markdown(doc) << '\n' 89 | end 90 | end 91 | 92 | private def self.parse_markdown(str : String) : String 93 | doc = Markd::Parser.parse str 94 | (@@renderer ||= Renderer.new Markd::Options.new).render(doc) 95 | end 96 | end 97 | end 98 | -------------------------------------------------------------------------------- /src/formatters/default/signature.cr: -------------------------------------------------------------------------------- 1 | module Docr::Formatters 2 | class Default 3 | def self.format_path(path : String, color : Colorize::ColorANSI) : String 4 | path 5 | .gsub(/([^():|, ]+)/, &.colorize(color)) 6 | .gsub(/(\*\*?)/, &.colorize.red) 7 | end 8 | 9 | def self.signature(io : IO, type : Redoc::Const, full : Bool, with_value : Bool) : Nil 10 | if full && (parent = type.parent) 11 | io << format_path parent.full_name, :blue 12 | io << "::" 13 | end 14 | 15 | io << format_path type.name, :blue 16 | if with_value 17 | io << " = " << type.value 18 | end 19 | io << '\n' 20 | end 21 | 22 | {% for type in %w[Module Class Struct] %} 23 | def self.signature(io : IO, type : Redoc::{{type.id}}, full : Bool, with_parent : Bool) : Nil 24 | {% unless type == "Module" %}io << "abstract ".colorize.red if type.abstract?{% end %} 25 | io << {{type.downcase}}.colorize.red 26 | io << ' ' << format_path((full ? type.full_name : type.name), :magenta) 27 | 28 | {% unless type == "Module" %} 29 | if with_parent && (parent = type.parent) 30 | io << " < " << format_path parent.full_name, :magenta 31 | end 32 | {% end %} 33 | io << '\n' 34 | end 35 | {% end %} 36 | 37 | def self.signature(io : IO, type : Redoc::Enum, full : Bool, with_base : Bool) : Nil 38 | io << "enum ".colorize.red 39 | io << format_path((full ? type.full_name : type.name), :magenta) 40 | 41 | if with_base && (base = type.type) 42 | io << " : " << format_path base, :magenta 43 | end 44 | io << '\n' 45 | end 46 | 47 | def self.signature(io : IO, type : Redoc::Alias, full : Bool, with_value : Bool) : Nil 48 | io << "alias ".colorize.red 49 | io << format_path((full ? type.full_name : type.name), :magenta) 50 | 51 | if with_value 52 | io << " = " << format_path type.type, :blue 53 | end 54 | io << '\n' 55 | end 56 | 57 | def self.signature(io : IO, type : Redoc::Annotation, full : Bool, __) : Nil 58 | io << "annotation ".colorize.red 59 | io << format_path((full ? type.full_name : type.name), :magenta) 60 | io << '\n' 61 | end 62 | 63 | def self.signature(io : IO, type : Redoc::Def, with_parent : Bool, with_self : Bool) : Nil 64 | io << "abstract ".colorize.red if type.abstract? 65 | io << "def ".colorize.red 66 | 67 | if with_parent && (parent = type.parent) 68 | io << format_path parent.full_name, :blue 69 | io << (type.html_id.ends_with?("-class-method") ? "." : "#") 70 | elsif with_self 71 | io << "self.".colorize.magenta 72 | end 73 | io << type.name.colorize.magenta 74 | 75 | unless type.params.empty? 76 | io << '(' 77 | format io, type.params[0] 78 | 79 | if type.params.size > 1 80 | type.params[1..].each do |param| 81 | io << ", " 82 | format io, param 83 | end 84 | end 85 | 86 | io << ')' 87 | end 88 | 89 | if ret = type.return_type 90 | io << " : " << format_path ret, :blue 91 | end 92 | 93 | if type.generic? 94 | io << " forall ".colorize.red 95 | type.free_vars.join(io, ", ") { |v, str| str << v.colorize.blue } 96 | end 97 | io << '\n' 98 | end 99 | 100 | def self.signature(io : IO, type : Redoc::Macro, with_parent : Bool, __) : Nil 101 | io << "macro ".colorize.red 102 | 103 | if with_parent && (parent = type.parent) 104 | io << format_path parent.full_name, :blue 105 | io << '.' 106 | end 107 | io << type.name.colorize.magenta 108 | 109 | unless type.params.empty? 110 | io << '(' 111 | format io, type.params[0] 112 | 113 | if type.params.size > 1 114 | type.params[1..].each do |param| 115 | io << ", " 116 | format io, param 117 | end 118 | end 119 | 120 | io << ')' 121 | end 122 | io << '\n' 123 | end 124 | 125 | private def self.format(io : IO, type : Redoc::Parameter) : Nil 126 | io << '*'.colorize.red if type.splat? 127 | io << "**".colorize.red if type.double_splat? 128 | io << '&'.colorize.red if type.block? 129 | io << type.name 130 | 131 | if rest = type.type 132 | io << " : " << rest 133 | end 134 | 135 | if value = type.default_value 136 | io << " = " << value 137 | end 138 | end 139 | end 140 | end 141 | -------------------------------------------------------------------------------- /src/formatters/default/tree.cr: -------------------------------------------------------------------------------- 1 | module Docr::Formatters 2 | class Default 3 | include Base 4 | 5 | private getter io : IO 6 | private getter indent : Int32 = 0 7 | private getter? locations : Bool 8 | 9 | def self.tree(io : IO, type : Redoc::Library | Redoc::Type, includes : Array(String), 10 | locations : Bool) : Nil 11 | new(io, includes, locations).format(type) 12 | end 13 | 14 | private def initialize(@io : IO, includes : Array(String), @locations : Bool) 15 | apply includes 16 | end 17 | 18 | private def indent(value : Int32) : Nil 19 | @indent += value 20 | end 21 | 22 | private def format_namespace(type : Redoc::Namespace) : Nil 23 | newline = false 24 | 25 | {% for type in %w[constants modules classes structs enums aliases annotations] %} 26 | if {{type.id}}? && !type.{{type.id}}.empty? 27 | newline = true 28 | io << (" " * indent) 29 | format type.{{type.id}}[0] 30 | 31 | if type.{{type.id}}.size > 1 32 | type.{{type.id}}.skip(1).each do |%type| 33 | {% unless type == "constants" %}io << '\n'{% end %} 34 | io << (" " * indent) 35 | format %type 36 | end 37 | end 38 | 39 | io << '\n' if newline 40 | newline = false 41 | end 42 | {% end %} 43 | end 44 | 45 | def format(type : Redoc::Library) : Nil 46 | io << "# Top Level Namespace\n\n".colorize.dark_gray 47 | 48 | if defs? && !type.methods.empty? 49 | type.methods.each do |method| 50 | format method 51 | end 52 | io << '\n' 53 | end 54 | 55 | if macros? && !type.macros.empty? 56 | type.macros.each do |method| 57 | format method 58 | end 59 | io << '\n' 60 | end 61 | 62 | format_namespace type 63 | end 64 | 65 | def format(type : Redoc::Const) : Nil 66 | return unless constants? 67 | 68 | if locations? 69 | if type.top_level? 70 | io << "# top level namespace\n".colorize.dark_gray 71 | else 72 | io << "(cannot resolve location)\n".colorize.dark_gray 73 | end 74 | io << (" " * indent) 75 | end 76 | 77 | Default.signature io, type, false, false 78 | end 79 | 80 | {% for type, guard in {Module: :modules?, Class: :classes?, Struct: :structs?} %} 81 | def format(type : Redoc::{{type.id}}) : Nil 82 | return unless {{guard.id}} 83 | 84 | if locations? 85 | if url = type.locations[0]?.try(&.url) 86 | Colorize.with.dark_gray.surround(io) do 87 | io << "# " << url << '\n' 88 | end 89 | else 90 | io << "(cannot resolve location)\n".colorize.dark_gray 91 | end 92 | io << (" " * indent) 93 | end 94 | 95 | Default.signature io, type, false, true 96 | indent 2 97 | 98 | has_includes = has_defs = false 99 | 100 | unless type.includes.empty? 101 | has_includes = true 102 | 103 | type.includes.each do |ref| 104 | io << (" " * indent) 105 | io << "include ".colorize.red 106 | io << Default.format_path ref.full_name, :magenta 107 | io << '\n' 108 | end 109 | end 110 | 111 | unless type.extends.empty? 112 | io << '\n' if has_includes 113 | has_includes = true 114 | 115 | type.extends.each do |ref| 116 | io << (" " * indent) 117 | io << "extend ".colorize.red 118 | 119 | if ref.full_name == type.full_name 120 | io << "self".colorize.blue 121 | else 122 | io << Default.format_path ref.full_name, :magenta 123 | end 124 | 125 | io << '\n' 126 | end 127 | end 128 | 129 | io << '\n' if has_includes 130 | format_namespace type 131 | 132 | if defs? && !type.class_methods.empty? 133 | has_defs = true 134 | 135 | type.class_methods.each do |method| 136 | io << '\n' if locations? 137 | io << (" " * indent) 138 | format method, true 139 | end 140 | end 141 | 142 | {% unless type == "Module" %} 143 | if defs? && !type.constructors.empty? 144 | io << '\n' if has_defs 145 | has_defs = true 146 | 147 | type.constructors.each do |method| 148 | io << '\n' if locations? 149 | io << (" " * indent) 150 | format method, true 151 | end 152 | end 153 | {% end %} 154 | 155 | if defs? && !type.instance_methods.empty? 156 | io << '\n' if has_defs 157 | has_defs = true 158 | 159 | type.instance_methods.each do |method| 160 | io << '\n' if locations? 161 | io << (" " * indent) 162 | format method 163 | end 164 | end 165 | 166 | if macros? && !type.macros.empty? 167 | io << '\n' if has_defs 168 | 169 | type.macros.each do |method| 170 | io << '\n' if locations? 171 | io << (" " * indent) 172 | format method 173 | end 174 | end 175 | 176 | indent -2 177 | io << (" " * indent) << "end\n".colorize.red 178 | end 179 | {% end %} 180 | 181 | def format(type : Redoc::Enum) : Nil 182 | return unless enums? 183 | 184 | if locations? 185 | if url = type.locations[0]?.try(&.url) 186 | Colorize.with.dark_gray.surround(io) do 187 | io << "# " << url << '\n' 188 | end 189 | else 190 | io << "(cannot resolve location)\n".colorize.dark_gray 191 | end 192 | io << (" " * indent) 193 | end 194 | 195 | Default.signature io, type, false, true 196 | indent 2 197 | 198 | type.constants.each do |const| 199 | io << (" " * indent) 200 | Default.signature io, const, true, false 201 | end 202 | 203 | indent -2 204 | io << (" " * indent) << "end\n".colorize.red 205 | end 206 | 207 | def format(type : Redoc::Alias) : Nil 208 | return unless aliases? 209 | 210 | if locations? 211 | if url = type.locations[0]?.try(&.url) 212 | Colorize.with.dark_gray.surround(io) do 213 | io << "# " << url << '\n' 214 | end 215 | else 216 | io << "(cannot resolve location)\n".colorize.dark_gray 217 | end 218 | io << (" " * indent) 219 | end 220 | 221 | Default.signature io, type, true, false 222 | end 223 | 224 | def format(type : Redoc::Annotation) : Nil 225 | return unless annotations? 226 | 227 | if locations? 228 | if url = type.locations[0]?.try(&.url) 229 | Colorize.with.dark_gray.surround(io) do 230 | io << "# " << url << '\n' 231 | end 232 | else 233 | io << "(cannot resolve location)\n".colorize.dark_gray 234 | end 235 | io << (" " * indent) 236 | end 237 | 238 | Default.signature io, type, false, nil 239 | end 240 | 241 | def format(type : Redoc::Def, with_self : Bool = false) : Nil 242 | return unless defs? 243 | 244 | if locations? 245 | if url = type.location.try(&.url) 246 | Colorize.with.dark_gray.surround(io) do 247 | io << "# " << url << '\n' 248 | end 249 | else 250 | io << "(cannot resolve location)\n".colorize.dark_gray 251 | end 252 | io << (" " * indent) 253 | end 254 | 255 | Default.signature io, type, false, with_self 256 | end 257 | 258 | def format(type : Redoc::Macro) : Nil 259 | return unless macros? 260 | 261 | if locations? 262 | if url = type.location.try(&.url) 263 | Colorize.with.dark_gray.surround(io) do 264 | io << "# " << url << '\n' 265 | end 266 | else 267 | io << "(cannot resolve location)\n".colorize.dark_gray 268 | end 269 | io << (" " * indent) 270 | end 271 | 272 | Default.signature io, type, false, nil 273 | end 274 | end 275 | end 276 | -------------------------------------------------------------------------------- /src/formatters/signature.cr: -------------------------------------------------------------------------------- 1 | module Docr::Formatters 2 | class Signature 3 | include Base 4 | 5 | private getter io : IO 6 | private getter? locations : Bool 7 | 8 | def self.format(io : IO, type : Redoc::Library | Redoc::Type, includes : Array(String), 9 | locations : Bool) : Nil 10 | new(io, includes, locations).format(type) 11 | end 12 | 13 | private def initialize(@io : IO, includes : Array(String), @locations : Bool) 14 | apply includes 15 | end 16 | 17 | private def format_namespace(type : Redoc::Namespace) : Nil 18 | {% for type in %w[constants modules classes structs enums aliases annotations] %} 19 | if {{type.id}}? && !type.{{type.id}}.empty? 20 | format type.{{type.id}}[0] 21 | 22 | if type.{{type.id}}.size > 1 23 | type.{{type.id}}.skip(1).each do |%type| 24 | {% unless type == "constants" %}io << '\n'{% end %} 25 | format %type 26 | end 27 | end 28 | 29 | io << '\n' 30 | end 31 | {% end %} 32 | end 33 | 34 | def format(type : Redoc::Library) : Nil 35 | io << "# Top Level Namespace\n\n".colorize.dark_gray 36 | 37 | if defs? && !type.methods.empty? 38 | type.methods.each do |method| 39 | format method 40 | end 41 | io << '\n' 42 | end 43 | 44 | if macros? && !type.macros.empty? 45 | type.macros.each do |method| 46 | format method 47 | end 48 | io << '\n' 49 | end 50 | 51 | format_namespace type 52 | end 53 | 54 | def format(type : Redoc::Const) : Nil 55 | return unless constants? 56 | 57 | if locations? 58 | if type.top_level? 59 | io << "# top level namespace\n".colorize.dark_gray 60 | else 61 | io << "(cannot resolve location)\n".colorize.dark_gray 62 | end 63 | end 64 | 65 | Default.signature io, type, true, false 66 | end 67 | 68 | {% for type, guard in {Module: :modules?, Class: :classes?, Struct: :structs?} %} 69 | def format(type : Redoc::{{type.id}}) : Nil 70 | return unless {{guard.id}} 71 | 72 | if locations? 73 | if url = type.locations[0]?.try(&.url) 74 | Colorize.with.dark_gray.surround(io) do 75 | io << "# " << url << '\n' 76 | end 77 | else 78 | io << "(cannot resolve location)\n".colorize.dark_gray 79 | end 80 | end 81 | 82 | Default.signature io, type, true, true 83 | format_namespace type 84 | 85 | if defs? && !type.class_methods.empty? 86 | type.class_methods.each do |method| 87 | io << '\n' if locations? 88 | format method, true 89 | end 90 | end 91 | 92 | {% unless type == "Module" %} 93 | if defs? && !type.constructors.empty? 94 | type.constructors.each do |method| 95 | io << '\n' if locations? 96 | format method, true 97 | end 98 | end 99 | {% end %} 100 | 101 | if defs? && !type.instance_methods.empty? 102 | type.instance_methods.each do |method| 103 | io << '\n' if locations? 104 | format method 105 | end 106 | end 107 | 108 | if macros? && !type.macros.empty? 109 | type.macros.each do |method| 110 | io << '\n' if locations? 111 | format method 112 | end 113 | end 114 | end 115 | {% end %} 116 | 117 | def format(type : Redoc::Enum) : Nil 118 | return unless enums? 119 | 120 | if locations? 121 | if url = type.locations[0]?.try(&.url) 122 | Colorize.with.dark_gray.surround(io) do 123 | io << "# " << url << '\n' 124 | end 125 | else 126 | io << "(cannot resolve location)\n".colorize.dark_gray 127 | end 128 | end 129 | 130 | Default.signature io, type, true, true 131 | 132 | type.constants.each do |const| 133 | Default.signature io, const, true, false 134 | end 135 | end 136 | 137 | def format(type : Redoc::Alias) : Nil 138 | return unless aliases? 139 | 140 | if locations? 141 | if url = type.locations[0]?.try(&.url) 142 | Colorize.with.dark_gray.surround(io) do 143 | io << "# " << url << '\n' 144 | end 145 | else 146 | io << "(cannot resolve location)\n".colorize.dark_gray 147 | end 148 | end 149 | 150 | Default.signature io, type, true, false 151 | end 152 | 153 | def format(type : Redoc::Annotation) : Nil 154 | return unless annotations? 155 | 156 | if locations? 157 | if url = type.locations[0]?.try(&.url) 158 | Colorize.with.dark_gray.surround(io) do 159 | io << "# " << url << '\n' 160 | end 161 | else 162 | io << "(cannot resolve location)\n".colorize.dark_gray 163 | end 164 | end 165 | 166 | Default.signature io, type, true, nil 167 | end 168 | 169 | def format(type : Redoc::Def, with_self : Bool = false) : Nil 170 | return unless defs? 171 | 172 | if locations? 173 | if url = type.location.try(&.url) 174 | Colorize.with.dark_gray.surround(io) do 175 | io << "# " << url << '\n' 176 | end 177 | else 178 | io << "(cannot resolve location)\n".colorize.dark_gray 179 | end 180 | end 181 | 182 | Default.signature io, type, true, false 183 | end 184 | 185 | def format(type : Redoc::Macro) : Nil 186 | return unless macros? 187 | 188 | if locations? 189 | if url = type.location.try(&.url) 190 | Colorize.with.dark_gray.surround(io) do 191 | io << "# " << url << '\n' 192 | end 193 | else 194 | io << "(cannot resolve location)\n".colorize.dark_gray 195 | end 196 | end 197 | 198 | Default.signature io, type, true, nil 199 | end 200 | end 201 | end 202 | -------------------------------------------------------------------------------- /src/library.cr: -------------------------------------------------------------------------------- 1 | module Docr::Library 2 | def self.exists?(name : String, version : String? = nil) : Bool 3 | if version 4 | File.exists?(LIBRARY_DIR / name / (version + ".json")) 5 | else 6 | Dir.exists?(LIBRARY_DIR / name) && !get_versions_for(name).empty? 7 | end 8 | end 9 | 10 | def self.list_all : Hash(String, Array(String)) 11 | libs = {} of String => Array(String) 12 | 13 | Dir.each_child(LIBRARY_DIR) do |child| 14 | next unless File.directory?(LIBRARY_DIR / child) 15 | versions = get_versions_for child 16 | next if versions.empty? 17 | 18 | libs[child] = versions 19 | end 20 | 21 | libs 22 | rescue 23 | Dir.mkdir_p LIBRARY_DIR 24 | 25 | libs.not_nil! # ameba:disable Lint/NotNil 26 | end 27 | 28 | def self.get_versions_for(name : String) : Array(String) 29 | versions = [] of String 30 | 31 | Dir.each_child(LIBRARY_DIR / name) do |child| 32 | next unless child.ends_with? ".json" 33 | versions << child.chomp ".json" 34 | end 35 | 36 | zero = SemanticVersion.new(0, 0, 0) 37 | 38 | versions.sort_by! { |v| SemanticVersion.parse(v) rescue zero } 39 | end 40 | 41 | def self.get(name : String, version : String) : Redoc::Library 42 | File.open(LIBRARY_DIR / name / (version + ".json")) do |file| 43 | Redoc::Library.from_json file 44 | end 45 | end 46 | 47 | def self.get_source(name : String) : String 48 | File.read LIBRARY_DIR / name / "SOURCE" 49 | end 50 | 51 | def self.delete(name : String, version : String?) : Nil 52 | if version 53 | File.delete(LIBRARY_DIR / name / (version + ".json")) 54 | else 55 | FileUtils.rm_rf(LIBRARY_DIR / name) 56 | end 57 | end 58 | end 59 | -------------------------------------------------------------------------------- /src/main.cr: -------------------------------------------------------------------------------- 1 | require "./docr" 2 | 3 | Docr::App.new.execute ARGV 4 | -------------------------------------------------------------------------------- /src/renderer.cr: -------------------------------------------------------------------------------- 1 | module Docr 2 | class Renderer < Markd::Renderer 3 | def heading(node : Markd::Node, entering : Bool) : Nil 4 | level = node.data["level"].as(Int32) 5 | 6 | if entering 7 | literal "\n" 8 | 9 | if level == 1 10 | literal "\e[45;97m " 11 | else 12 | literal "\e[34m" 13 | literal "#" * level 14 | literal " " 15 | end 16 | else 17 | literal " " if level == 1 18 | literal "\e[0m\n\n" 19 | end 20 | end 21 | 22 | def code(node : Markd::Node, __) : Nil 23 | literal(String.build do |io| 24 | Colorize.with.back(236).fore(203).surround(io) do 25 | io << ' ' << node.text << ' ' 26 | end 27 | end) 28 | end 29 | 30 | def code_block(node : Markd::Node, __) : Nil 31 | literal(String.build do |io| 32 | io << '\n' 33 | {% if flag?(:tzcolors) %} 34 | Tartrazine.to_ansi(node.text, "crystal", "github-dark").each_line do |line| 35 | io << " " << line << '\n' 36 | end 37 | {% else %} 38 | Colorize.with.fore(244).surround(io) do 39 | node.text.each_line do |line| 40 | io << " " << line << '\n' 41 | end 42 | end 43 | io << '\n' 44 | {% end %} 45 | end) 46 | end 47 | 48 | def thematic_break(node : Markd::Node, __) : Nil 49 | literal "\n————————————\n".colorize.dark_gray.to_s 50 | end 51 | 52 | def block_quote(node : Markd::Node, entering : Bool) : Nil 53 | # literal "┃ ".colorize.dark_gray.to_s if entering 54 | literal "\n" unless entering 55 | end 56 | 57 | def list(node : Markd::Node, entering : Bool) : Nil 58 | literal "\n" unless entering 59 | end 60 | 61 | def item(node : Markd::Node, entering : Bool) : Nil 62 | literal "• " if entering 63 | end 64 | 65 | def link(node : Markd::Node, __) : Nil 66 | end 67 | 68 | def image(node : Markd::Node, __) : Nil 69 | literal node.text 70 | end 71 | 72 | def html_block(node : Markd::Node, __) : Nil 73 | literal "\n" 74 | literal node.text 75 | literal "\n" 76 | end 77 | 78 | def html_inline(node : Markd::Node, __) : Nil 79 | literal "\n" 80 | end 81 | 82 | def paragraph(node : Markd::Node, entering : Bool) : Nil 83 | literal "\n" unless entering 84 | end 85 | 86 | def emphasis(node : Markd::Node, __) : Nil 87 | literal node.text.colorize.italic.to_s 88 | end 89 | 90 | def soft_break(node : Markd::Node, __) : Nil 91 | literal " " 92 | end 93 | 94 | def line_break(node : Markd::Node, __) : Nil 95 | literal "\n" 96 | end 97 | 98 | def strong(node : Markd::Node, __) : Nil 99 | literal node.text.colorize.bold.to_s 100 | end 101 | 102 | def text(node : Markd::Node, __) : Nil 103 | literal node.text 104 | end 105 | 106 | # Markd::Renderer isn't reusable by default... 107 | def render(document : Markd::Node) : String 108 | str = super 109 | @output_io = String::Builder.new 110 | str 111 | end 112 | end 113 | end 114 | --------------------------------------------------------------------------------