Merge pull request #3325 from Hannah-Sten/docs

Writerside documentation
Hannah-Sten · Jan 21, 2024 · 151aa4c · 151aa4c
2 parents 2ccc4dc + 69ce5f3
commit 151aa4c
Show file tree

Hide file tree

Showing 130 changed files with 7,091 additions and 0 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,110 @@
+name: Build docs
+
+on:
+  push:
+    branches: ["master", "docs"]
+  workflow_dispatch:
+
+# Gives the workflow permissions to clone the repo and create a page deployment
+permissions:
+  id-token: write
+  pages: write
+
+env:
+  PRODUCT: Writerside/texify-docs
+  DOC_ARTIFACT: webHelpTEXIFY-DOCS2-all.zip
+  ALGOLIA_ARTIFACT: algolia-indexes-TEXIFY-DOCS.zip
+  ALGOLIA_APP_NAME: D5M21MXSWC
+  ALGOLIA_INDEX_NAME: TeXiFy-IDEA
+  ALGOLIA_KEY: ${{ secrets.ALGOLIA_KEY }}
+  CONFIG_JSON_PRODUCT: texify-docs
+  CONFIG_JSON_VERSION: master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Build Writerside docs using Docker
+        uses: JetBrains/writerside-github-action@v3
+      - name: Upload documentation
+        uses: actions/upload-artifact@v3
+        with:
+          name: docs
+          path: |
+            artifacts/${{ env.DOC_ARTIFACT }}
+            artifacts/report.json
+          retention-days: 7
+      - name: Upload algolia-indexes
+        uses: actions/upload-artifact@v3
+        with:
+          name: algolia-indexes
+          path: artifacts/${{ env.ALGOLIA_ARTIFACT }}
+          retention-days: 7
+  test:
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v1
+        with:
+          name: docs
+          path: artifacts
+
+      - name: Test documentation
+        uses: JetBrains/writerside-checker-action@v1
+        with:
+          instance: ${{ env.INSTANCE }}
+
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    # Requires the build results
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download artifact
+        uses: actions/download-artifact@v3
+        with:
+          name: docs
+      - name: Unzip artifact
+        uses: montudor/action-zip@v1
+        with:
+          args: unzip -qq ${{ env.DOC_ARTIFACT }} -d dir
+      - name: Setup Pages
+        uses: actions/configure-pages@v2
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: dir
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1
+
+  publish-indexes:
+    needs: build
+    runs-on: ubuntu-latest
+    container:
+      image: registry.jetbrains.team/p/writerside/builder/algolia-publisher:2.0.32-2
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/download-artifact@v3
+        with:
+          name: algolia-indexes
+      - uses: montudor/action-zip@v1
+        with:
+          args: unzip -qq ${{ env.ALGOLIA_ARTIFACT }} -d algolia-indexes
+      - run: |
+          env "algolia-key=${{env.ALGOLIA_KEY}}" java -jar /opt/builder/help-publication-agent.jar \
+          update-index \
+          --application-name ${{env.ALGOLIA_APP_NAME}} \
+          --index-name ${{env.ALGOLIA_INDEX_NAME}} \
+          --product ${{env.CONFIG_JSON_PRODUCT}} \
+          --version ${{env.CONFIG_JSON_VERSION}} \
+          --index-directory algolia-indexes/ \
+          2>&1 | tee algolia-update-index-log.txt
diff --git a/.idea/.gitignore b/.idea/.gitignore
diff --git a/Release-checklist.md b/Release-checklist.md
@@ -0,0 +1,18 @@
+- [ ] Create branch bx.x.x
+- [ ] Run 'Usage of IntelliJ API not available in older IDEs' and 'Stateful extension' inspection (ctrl+alt+shift+i)
+- [ ] Increase stub version in LatexParserDefinition
+- [ ] Re-include Sumatra dlls in build.gradle.kts to enable forward search
+- [ ] Run ctan.py
+
+- [ ] Add welcome text to Changelog.md
+- [ ] Update welcome text
+- [ ] Update version in gradle.properties
+- [ ] run patchChangelog (ideally this would be done for the publishPlugin task, but somehow that produces an 'Unreleased' title instead of 0.x.x)
+- [ ] Delete alpha versions from changelog
+- [ ] runIDE and check the changelog is formatted correctly
+- [ ] Run publishPlugin
+- [ ] Merge PR
+- [ ] buildPlugin and release on GitHub, tag version: v0.x.x and release title: Beta x.x.x
+- [ ] Close the milestone
+- [ ] Update MiKTeX Docker image
+- [ ] Check performance: indexing texlive full should take around one minute, inspections on a 10k line file should take around 10 seconds, pressing enter in such a file should react within a second.
diff --git a/Writerside/c.list b/Writerside/c.list
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE categories
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/categories.dtd">
+<categories>
+    <category id="wrs" name="Writerside documentation" order="1"/>
+</categories>
diff --git a/Writerside/cfg/buildprofiles.xml b/Writerside/cfg/buildprofiles.xml
@@ -0,0 +1,13 @@
+<buildprofiles xsi:noNamespaceSchemaLocation="https://helpserver.labs.jb.gg/help/schemas/mvp/build-profiles.xsd"
+               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+    <variables>
+        <algolia-id>D5M21MXSWC</algolia-id>
+        <algolia-index>TeXiFy-IDEA</algolia-index>
+        <algolia-api-key>24051865ac9a05c6332f3e3c04468ea5</algolia-api-key>
+        <config-search-scopes-provider>https://www.jetbrains.com/</config-search-scopes-provider>
+
+        <enable-browser-edits>true</enable-browser-edits>
+        <browser-edits-url>https://github.com/Hannah-Sten/TeXiFy-IDEA/edit/master/Writerside/</browser-edits-url>
+    </variables>
+    <build-profile instance="texify-docs"/>
+</buildprofiles>
diff --git a/Writerside/cfg/platforms.xml b/Writerside/cfg/platforms.xml
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<platforms>
+    <platform id="primary">
+        <use-keymaps>
+            primary_Windows_Linux
+        </use-keymaps>
+        <use-keymaps>
+            primary_macOS
+        </use-keymaps>
+        <src>keymap.xml</src>
+    </platform>
+</platforms>
diff --git a/Writerside/images/bibtex/bibtex-autocomplete.png b/Writerside/images/bibtex/bibtex-autocomplete.png
diff --git a/Writerside/images/bibtex/bibtex-folding.png b/Writerside/images/bibtex/bibtex-folding.png
diff --git a/Writerside/images/bibtex/bibtex-safe-delete-entry.png b/Writerside/images/bibtex/bibtex-safe-delete-entry.png
diff --git a/Writerside/images/edit-page.png b/Writerside/images/edit-page.png
diff --git a/Writerside/images/editing/code-completion/brace-matching.png b/Writerside/images/editing/code-completion/brace-matching.png
diff --git a/Writerside/images/editing/code-completion/brace-matching2.png b/Writerside/images/editing/code-completion/brace-matching2.png
diff --git a/Writerside/images/editing/code-completion/brace-matching2_dark.png b/Writerside/images/editing/code-completion/brace-matching2_dark.png
diff --git a/Writerside/images/editing/code-completion/brace-matching_dark.png b/Writerside/images/editing/code-completion/brace-matching_dark.png
diff --git a/Writerside/images/editing/code-completion/command-autocomplete1.png b/Writerside/images/editing/code-completion/command-autocomplete1.png
diff --git a/Writerside/images/editing/code-completion/command-autocomplete2.png b/Writerside/images/editing/code-completion/command-autocomplete2.png
diff --git a/Writerside/images/editing/code-completion/copilot.png b/Writerside/images/editing/code-completion/copilot.png
diff --git a/Writerside/images/editing/code-completion/copilot2.png b/Writerside/images/editing/code-completion/copilot2.png
diff --git a/Writerside/images/editing/code-completion/itemize-enter.gif b/Writerside/images/editing/code-completion/itemize-enter.gif
diff --git a/Writerside/images/editing/code-completion/live-template-settings.png b/Writerside/images/editing/code-completion/live-template-settings.png
diff --git a/Writerside/images/editing/code-completion/live-templates.gif b/Writerside/images/editing/code-completion/live-templates.gif
diff --git a/Writerside/images/editing/code-completion/math-postfix.gif b/Writerside/images/editing/code-completion/math-postfix.gif
diff --git a/Writerside/images/editing/code-completion/miktex-admin.PNG b/Writerside/images/editing/code-completion/miktex-admin.PNG
diff --git a/Writerside/images/editing/code-completion/miktex-linux.png b/Writerside/images/editing/code-completion/miktex-linux.png
diff --git a/Writerside/images/editing/code-completion/required-parameters-autocomplete.gif b/Writerside/images/editing/code-completion/required-parameters-autocomplete.gif
diff --git a/Writerside/images/editing/code-completion/required-parameters-environments.gif b/Writerside/images/editing/code-completion/required-parameters-environments.gif
diff --git a/Writerside/images/editing/code-completion/text-postfix.gif b/Writerside/images/editing/code-completion/text-postfix.gif
diff --git a/Writerside/images/editing/code-completion/xparse-autocomplete.png b/Writerside/images/editing/code-completion/xparse-autocomplete.png
diff --git a/Writerside/images/editing/code-completion/xparse-autocomplete_dark.png b/Writerside/images/editing/code-completion/xparse-autocomplete_dark.png
diff --git a/Writerside/images/editing/code-formatting/blank-lines-section.gif b/Writerside/images/editing/code-formatting/blank-lines-section.gif
diff --git a/Writerside/images/editing/code-formatting/hard-wrap.gif b/Writerside/images/editing/code-formatting/hard-wrap.gif
diff --git a/Writerside/images/editing/code-formatting/indent-environment.gif b/Writerside/images/editing/code-formatting/indent-environment.gif
diff --git a/Writerside/images/editing/code-formatting/indent-group.gif b/Writerside/images/editing/code-formatting/indent-group.gif
diff --git a/Writerside/images/editing/code-formatting/table-formatter-multiline.gif b/Writerside/images/editing/code-formatting/table-formatter-multiline.gif
diff --git a/Writerside/images/editing/code-formatting/table-formatter-simple.gif b/Writerside/images/editing/code-formatting/table-formatter-simple.gif
diff --git a/Writerside/images/editing/code-navigation/externaldocument-usages.png b/Writerside/images/editing/code-navigation/externaldocument-usages.png
diff --git a/Writerside/images/editing/code-navigation/find-usages.png b/Writerside/images/editing/code-navigation/find-usages.png
diff --git a/Writerside/images/editing/code-navigation/go-to-cite-declaration.gif b/Writerside/images/editing/code-navigation/go-to-cite-declaration.gif
diff --git a/Writerside/images/editing/code-navigation/go-to-file-inclusion.gif b/Writerside/images/editing/code-navigation/go-to-file-inclusion.gif
diff --git a/Writerside/images/editing/code-navigation/go-to-label-declaration.gif b/Writerside/images/editing/code-navigation/go-to-label-declaration.gif
diff --git a/Writerside/images/editing/code-navigation/peek-definition.png b/Writerside/images/editing/code-navigation/peek-definition.png
diff --git a/Writerside/images/editing/code-navigation/peek-definition_dark.png b/Writerside/images/editing/code-navigation/peek-definition_dark.png
diff --git a/Writerside/images/editing/code-navigation/structure-view.png b/Writerside/images/editing/code-navigation/structure-view.png
diff --git a/Writerside/images/editing/code-navigation/structure-view_dark.png b/Writerside/images/editing/code-navigation/structure-view_dark.png
diff --git a/Writerside/images/editing/env-docs.png b/Writerside/images/editing/env-docs.png
diff --git a/Writerside/images/editing/env-docs_dark.png b/Writerside/images/editing/env-docs_dark.png
diff --git a/Writerside/images/editing/environment-switch.png b/Writerside/images/editing/environment-switch.png
diff --git a/Writerside/images/editing/environment-switch_dark.png b/Writerside/images/editing/environment-switch_dark.png
diff --git a/Writerside/images/editing/font-style.png b/Writerside/images/editing/font-style.png
diff --git a/Writerside/images/editing/font-style_dark.png b/Writerside/images/editing/font-style_dark.png
diff --git a/Writerside/images/editing/inline-command.gif b/Writerside/images/editing/inline-command.gif
diff --git a/Writerside/images/editing/inline-command_dark.gif b/Writerside/images/editing/inline-command_dark.gif
diff --git a/Writerside/images/editing/macro.png b/Writerside/images/editing/macro.png
diff --git a/Writerside/images/editing/move-argument.gif b/Writerside/images/editing/move-argument.gif
diff --git a/Writerside/images/editing/newfile.png b/Writerside/images/editing/newfile.png
diff --git a/Writerside/images/editing/newfile_dark.png b/Writerside/images/editing/newfile_dark.png
diff --git a/Writerside/images/editing/package-import.gif b/Writerside/images/editing/package-import.gif
diff --git a/Writerside/images/editing/paste-image-wizard.png b/Writerside/images/editing/paste-image-wizard.png
diff --git a/Writerside/images/editing/paste-image.mp4 b/Writerside/images/editing/paste-image.mp4
diff --git a/Writerside/images/editing/rename-navigate.gif b/Writerside/images/editing/rename-navigate.gif
diff --git a/Writerside/images/editing/rename-navigate_dark.gif b/Writerside/images/editing/rename-navigate_dark.gif
diff --git a/Writerside/images/editing/soft-wraps.png b/Writerside/images/editing/soft-wraps.png
diff --git a/Writerside/images/editing/soft-wraps_dark.png b/Writerside/images/editing/soft-wraps_dark.png
diff --git a/Writerside/images/editing/surround.png b/Writerside/images/editing/surround.png
diff --git a/Writerside/images/editing/surround_dark.png b/Writerside/images/editing/surround_dark.png
diff --git a/Writerside/images/editing/texdoc.png b/Writerside/images/editing/texdoc.png
diff --git a/Writerside/images/editing/texdoc_dark.png b/Writerside/images/editing/texdoc_dark.png
diff --git a/Writerside/images/inspections/grazie.png b/Writerside/images/inspections/grazie.png
diff --git a/Writerside/images/inspections/suppression-menu.png b/Writerside/images/inspections/suppression-menu.png
diff --git a/Writerside/images/inspections/suppression.png b/Writerside/images/inspections/suppression.png
diff --git a/Writerside/images/install.png b/Writerside/images/install.png
diff --git a/Writerside/images/install_dark.png b/Writerside/images/install_dark.png
diff --git a/Writerside/images/project-configuration/project-sdk.png b/Writerside/images/project-configuration/project-sdk.png
diff --git a/Writerside/images/project-configuration/project-sdk_dark.png b/Writerside/images/project-configuration/project-sdk_dark.png
diff --git a/Writerside/images/project-configuration/sdk.png b/Writerside/images/project-configuration/sdk.png
diff --git a/Writerside/images/project-configuration/sdk_dark.png b/Writerside/images/project-configuration/sdk_dark.png
diff --git a/Writerside/images/reading/color-gutter.png b/Writerside/images/reading/color-gutter.png
diff --git a/Writerside/images/reading/line-markers.png b/Writerside/images/reading/line-markers.png
diff --git a/Writerside/images/reading/syntax-highlighting.png b/Writerside/images/reading/syntax-highlighting.png
diff --git a/Writerside/images/running/autocompile.gif b/Writerside/images/running/autocompile.gif
diff --git a/Writerside/images/running/built-in-pdf-viewer.gif b/Writerside/images/running/built-in-pdf-viewer.gif
diff --git a/Writerside/images/running/change-compiler.gif b/Writerside/images/running/change-compiler.gif
diff --git a/Writerside/images/running/log-tab.png b/Writerside/images/running/log-tab.png
diff --git a/Writerside/images/settings/continuous-preview.gif b/Writerside/images/settings/continuous-preview.gif
diff --git a/Writerside/images/settings/folding.png b/Writerside/images/settings/folding.png
diff --git a/Writerside/images/settings/language-injection.png b/Writerside/images/settings/language-injection.png
diff --git a/Writerside/images/settings/set-up-sdk.png b/Writerside/images/settings/set-up-sdk.png
diff --git a/Writerside/images/tools/citefromremote.gif b/Writerside/images/tools/citefromremote.gif
diff --git a/Writerside/images/tools/insert-graphic-wizard.gif b/Writerside/images/tools/insert-graphic-wizard.gif
diff --git a/Writerside/images/tools/insert-table-wizard.gif b/Writerside/images/tools/insert-table-wizard.gif
diff --git a/Writerside/images/tools/insert-table-wizard.png b/Writerside/images/tools/insert-table-wizard.png
diff --git a/Writerside/images/tools/symbols-tool-window.png b/Writerside/images/tools/symbols-tool-window.png
diff --git a/Writerside/keymap.xml b/Writerside/keymap.xml
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Keymap id="texify-docs">
+    <Action id="$Reformat">
+        <Shortcut layout="primary_Windows_Linux">Ctrl+Alt+L</Shortcut>
+        <Shortcut layout="primary_macOS">Meta+Alt+L</Shortcut>
+    </Action>
+    <Action id="$Commit">
+        <Shortcut layout="primary_Windows_Linux">Ctrl+K</Shortcut>
+        <Shortcut layout="primary_macOS">Meta+K</Shortcut>
+    </Action>
+    <Action id="$Pull">
+        <Shortcut layout="primary_Windows_Linux">Ctrl+T</Shortcut>
+        <Shortcut layout="primary_macOS">Meta+T</Shortcut>
+    </Action>
+</Keymap>
diff --git a/Writerside/project.ihp b/Writerside/project.ihp
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE ihp SYSTEM "https://resources.jetbrains.com/writerside/1.0/ihp.dtd">
+
+<ihp version="2.0">
+    <topics dir="topics"/>
+    <images dir="images" web-path="TeXiFy-IDEA"/>
+    <instance src="texify-docs.tree" web-path="/texify-docs/" />
+</ihp>
diff --git a/Writerside/texify-docs.tree b/Writerside/texify-docs.tree
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE instance-profile
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
+
+<instance-profile id="texify-docs"
+                 name="TeXiFy-IDEA documentation"
+                 start-page="Welcome.topic">
+
+    <toc-element topic="Welcome.topic"/>
+    <toc-element topic="Quick-start-guide.md"/>
+    <toc-element topic="Installation-guide.md"/>
+    <toc-element topic="Installing-pre-release-builds.md"/>
+    <toc-element topic="Project-configuration.md"/>
+    <toc-element topic="Editing-a-LaTeX-file.md">
+        <toc-element topic="Code-completion.md"/>
+        <toc-element topic="Code-formatting.md"/>
+        <toc-element topic="Code-navigation.md"/>
+    </toc-element>
+    <toc-element topic="Running-a-LaTeX-file.md">
+        <toc-element topic="Run-configuration-settings.md"/>
+        <toc-element topic="PDF-viewers.md"/>
+        <toc-element topic="External-tools.md"/>
+    </toc-element>
+    <toc-element topic="BibTeX.md"/>
+    <toc-element toc-title="Settings">
+        <toc-element topic="TeXiFy-settings.md"/>
+        <toc-element topic="Editor.md">
+            <toc-element topic="General.md"/>
+            <toc-element topic="Code-Style.md"/>
+        </toc-element>
+    </toc-element>
+    <toc-element topic="Tools.md">
+        <toc-element topic="Tool-Windows.md"/>
+    </toc-element>
+    <toc-element topic="Inspections.md">
+        <toc-element topic="BibTeX-Inspections.md"/>
+        <toc-element topic="Typesetting-issues.md"/>
+        <toc-element topic="Spacing.md"/>
+        <toc-element topic="Code-style-issues.md"/>
+        <toc-element topic="Probable-bugs.md"/>
+        <toc-element topic="Packages.md"/>
+        <toc-element topic="Redundant-code.md"/>
+        <toc-element topic="Discouraged-or-obsolete-code.md"/>
+        <toc-element topic="Intentions.md"/>
+    </toc-element>
+    <toc-element toc-title="Reference">
+        <toc-element topic="Errors-and-warnings.md"/>
+    </toc-element>
+    <toc-element topic="Contributing-to-the-documentation.md"/>
+    <toc-element topic="Contributing-to-the-source-code.md"/>
+    <toc-element topic="Troubleshooting.md"/>
+</instance-profile>
diff --git a/Writerside/topics/BibTeX-Inspections.md b/Writerside/topics/BibTeX-Inspections.md
@@ -0,0 +1,29 @@
+# BibTeX Inspections
+
+## Duplicate ID
+
+You cannot have two bibtex entries with the same id.
+
+## Missing bibliography style
+
+When you include a bibliography, you should also define a bibliography style, for example `\bibliographystyle{plain}`.
+
+## Duplicate bibliography style commands
+
+You should only have one `\bibliographystyle` command.
+
+## Same bibliography is included multiple times
+
+It is not useful to include the same bibliography in the same document multiple times.
+
+## Bib entry is not cited
+
+_Since b0.7.3_
+
+This inspection detects entries in bibliographies that are not cited in the main document.
+It greys out the identifier of the entry, and provides a quick fix to safe delete this entry.
+When using the safe deletion, TeXiFy will also search for cites that appear in comments, and you will be warned if any are found, see Figure 1.
+
+**View of the safe delete that found a usage in a comment.**
+
+![bibtex-safe-delete-entry](bibtex-safe-delete-entry.png)