Merge pull request #143 from cozy/add-ach

feat: Add ACH documentation

Author: ptbrowne

OUTSIDE_DOCS

@@ -15,3 +15,4 @@ eslint-config-cozy-app https://github.com/cozy/cozy-libs.git packages/eslint-con
 cozy-flags https://github.com/cozy/cozy-libs.git packages/cozy-flags
 cozy-realtime https://github.com/cozy/cozy-libs.git packages/cozy-realtime
 cozy-banks https://github.com/cozy/cozy-banks.git .
+ach https://github.com/cozy/ach.git .

README.md

@@ -38,7 +38,7 @@ to search for information only in one location.
 Each repository maintains its own [table of contents](https://github.com/cozy/cozy-doctypes/blob/master/toc.yml),
 which controls what is shown under the References menu.
 
-See [./build.sh](./build.sh), and [./add_external_docs.py](./add_external_docs.py) scripts for more information.
+See [./build.sh](./build.sh), and [./generate_config.py](./generate_config.py) scripts for more information.
 
 The edit links displayed in the header of each article are modified via Javascript to handle outside repositories (mkdocs does not support
 this natively).

build.sh

@@ -6,6 +6,6 @@ rm -rf docs/*
 cp index.html docs/
 cp CNAME docs/
 
-python add_external_docs.py --fetch
+python generate_config.py --fetch
 
 mkdocs build -f mkdocs.yml

add_external_docs.py generate_config.pyadd_external_docs.py renamed to generate_config.py

@@ -1,6 +1,6 @@
 """
-Adds table of contents of each external documentation to the
-References menu
+- Fetches external repositories containing docs (listed in OUTSIDE_DOCS)
+- Generate mkdocs.yml from mkdocs.yml.tpl
 """
 
 import yaml
@@ -190,7 +190,7 @@ def main(argv):
     if '--fetch' in argv:
         fetch_all_external_docs_from_file(OUTSIDE_DOCS)
 
-    with open('./mkdocs.yml') as f:
+    with open('./mkdocs.yml.tpl') as f:
         data = ordered_load(f, yaml.SafeLoader)
 
     with open(OUTSIDE_DOCS) as f:
@@ -213,5 +213,10 @@ def main(argv):
 
     with open('mkdocs.yml', 'w+') as f:
         ordered_dump(data, f, indent=2, default_flow_style=False, Dumper=yaml.SafeDumper)
+        f.seek(0, 0)
+        content = f.read()
+        f.seek(0, 0)
+        warning = '#\n# THIS FILE IS AUTOMATICALLY GENERATED, PLEASE EDIT `mkdocs.yml.tpl` AND LAUNCH `python generate_config.py`\n#\n'
+        f.write(warning + content)
 
 main(sys.argv)

mkdocs.yml

@@ -1,3 +1,6 @@
+#
+# THIS FILE IS AUTOMATICALLY GENERATED, PLEASE EDIT `mkdocs.yml.tpl` AND LAUNCH `python generate_config.py`
+#
 site_name: Cozy Developer Documentation
 docs_dir: src
 site_url: https://docs.cozy.io/
@@ -35,25 +38,111 @@ nav:
     - Install Cozy Drive on GNU/Linux: howTos/sync/linux.md
 - Libraries:
   - Develop an application:
-    - Access data (client): <cozy-client>
-    - Build a UI (ui): <cozy-ui>
-    - Define data (doctypes): <cozy-doctypes>
+    - Define data (doctypes):
+      - README: cozy-doctypes/docs/README.md
+      - Accounts: cozy-doctypes/docs/io.cozy.accounts.md
+      - Apps: cozy-doctypes/docs/io.cozy.apps.md
+      - Banking doctypes: cozy-doctypes/docs/io.cozy.bank.md
+      - Bills: cozy-doctypes/docs/io.cozy.bills.md
+      - Connectors: cozy-doctypes/docs/io.cozy.konnectors.md
+      - Contacts: cozy-doctypes/docs/io.cozy.contacts.md
+      - Files: cozy-doctypes/docs/io.cozy.files.md
+      - Files metadata: cozy-doctypes/docs/io.cozy.files_metadata.md
+      - Identities: cozy-doctypes/docs/io.cozy.identities.md
+      - Notifications: cozy-doctypes/docs/io.cozy.notifications.md
+      - Remote requests: cozy-doctypes/docs/io.cozy.remote.requests.md
+      - Session logins: cozy-doctypes/docs/io.cozy.sessions.logins.md
+      - Permissions: cozy-doctypes/docs/io.cozy.permissions.md
+      - Photos Albums: cozy-doctypes/docs/io.cozy.photos.albums.md
+      - Procedures: cozy-doctypes/docs/io.cozy.procedures.md
+      - Sessions Logins: cozy-doctypes/docs/io.cozy.sessions.logins.md
+      - Settings: cozy-doctypes/docs/io.cozy.settings.md
+      - Sharings: cozy-doctypes/docs/io.cozy.sharings.md
+      - Accounts Types: cozy-doctypes/docs/io.cozy.account_types.md
+      - Autocategorization: cozy-doctypes/docs/cc.cozycloud.autocategorization.md
+      - Exports: cozy-doctypes/docs/io.cozy.exports.md
+      - Jobs: cozy-doctypes/docs/io.cozy.jobs.md
+      - OAuth Clients: cozy-doctypes/docs/io.cozy.oauth.clients.md
+      - OAuth Access Codes: cozy-doctypes/docs/io.cozy.oauth.access_codes.md
+      - Triggers: cozy-doctypes/docs/io.cozy.triggers.md
+      - Triggers state: cozy-doctypes/docs/io.cozy.triggers.state.md
+      - Remote requests: cozy-doctypes/docs/io.cozy.remote.requests.md
+      - Sessions: cozy-doctypes/docs/io.cozy.sessions.md
+      - Shared: cozy-doctypes/docs/io.cozy.shared.md
+      - Terms: cozy-doctypes/docs/io.cozy.terms.md
+      - Bets Unibet: cozy-doctypes/docs/com.unibet.bets.md
+    - Access data (client):
+      - Getting started: cozy-client/getting-started.md
+      - Using relationships: cozy-client/relationships.md
+      - cozyMetadata maintenance: cozy-client/metadata.md
+      - React integration: cozy-client/react-integration.md
+      - Other details: cozy-client/details.md
+      - Cozy Client API: cozy-client/api/cozy-client.md
+      - Cozy Pouch Link API: cozy-client/api/cozy-pouch-link.md
+      - Cozy Stack Client API: cozy-client/api/cozy-stack-client.md
+    - Build a UI (ui): cozy-ui/README.md
     - Advanced:
-      - Realtime data (realtime): <cozy-realtime>
-      - Native devices (device-helper): <cozy-device-helper>
+      - Realtime data (realtime): cozy-realtime/README.md
+      - Native devices (device-helper): cozy-device-helper/README.md
   - Develop a konnector:
-    - Scrape data (konnector-libs): <cozy-konnector-libs>
-    - konitor: <konitor>
-  - Publish on the store (app-publish): <cozy-app-publish>
+    - Scrape data (konnector-libs):
+      - README: cozy-konnector-libs/README.md
+      - API: cozy-konnector-libs/api.md
+      - CLI: cozy-konnector-libs/cli.md
+      - Develop: cozy-konnector-libs/dev.md
+      - Errors: cozy-konnector-libs/errors.md
+      - Operation linking: cozy-konnector-libs/operation-linking.md
+      - Synchronization: cozy-konnector-libs/synchronization.md
+    - konitor: konitor/cli.md
+  - Publish on the store (app-publish): cozy-app-publish/README.md
   - Dev tools:
-    - Babel preset: <babel-preset-cozy-app>
-    - Commitlint: <commitlint-config-cozy>
-    - ESLint: <eslint-config-cozy-app>
+    - Babel preset: babel-preset-cozy-app/README.md
+    - Commitlint: commitlint-config-cozy/README.md
+    - ESLint: eslint-config-cozy-app/README.md
+    - ACH: ach/README.md
   - Advanced:
-    - Stack server: <cozy-stack>
-    - Registry server: <cozy-apps-registry>
-- Applications:
-  - Cozy Banks: <cozy-banks>
+    - Stack server:
+      - README: cozy-stack/README.md
+      - Usage:
+        - Install the cozy-stack: cozy-stack/INSTALL.md
+        - Configuration file: cozy-stack/config.md
+        - Managing Instances: cozy-stack/instance.md
+        - Security: cozy-stack/security.md
+        - Manpages of the command-line tool: cozy-stack/cli/cozy-stack.md
+      - How-to guides for developpers:
+        - Develop a client-side app: cozy-stack/client-app-dev.md
+        - Running and building Docker images: cozy-stack/docker.md
+        - Adding a new doctype: cozy-stack/doctype.md
+        - Working with the stack assets: cozy-stack/assets.md
+        - Build a release: cozy-stack/release.md
+        - The contributing guide: cozy-stack/CONTRIBUTING.md
+      - Explanations:
+        - Sharing design: cozy-stack/sharing-design.md
+        - Workflow of the konnectors: cozy-stack/konnectors-workflow.md
+      - List of services:
+        - /auth - Authentication & OAuth: cozy-stack/auth.md
+        - /apps - Applications Management: cozy-stack/apps.md
+        - ' /apps - Apps registry': cozy-stack/registry.md
+        - ' /apps - Konnectors': cozy-stack/konnectors.md
+        - /data - Data System: cozy-stack/data-system.md
+        - ' /data - Mango': cozy-stack/mango.md
+        - ' /data - CouchDB Quirks': cozy-stack/couchdb-quirks.md
+        - ' /data - PouchDB Quirks': cozy-stack/pouchdb-quirks.md
+        - /files - Virtual File System: cozy-stack/files.md
+        - ' /files - References of documents in VFS': cozy-stack/references-docs-in-vfs.md
+        - /intents - Intents: cozy-stack/intents.md
+        - /jobs - Jobs: cozy-stack/jobs.md
+        - ' /jobs - Workers': cozy-stack/workers.md
+        - /move - Move, export and import an instance: cozy-stack/move.md
+        - /notifications - Notifications: cozy-stack/notifications.md
+        - /public - Public: cozy-stack/public.md
+        - /permissions - Permissions: cozy-stack/permissions.md
+        - /realtime - Realtime: cozy-stack/realtime.md
+        - /remote - Proxy for remote data/API: cozy-stack/remote.md
+        - /settings - Settings: cozy-stack/settings.md
+        - ' /settings - Terms of Services': cozy-stack/user-action-required.md
+        - /sharings - Sharing: cozy-stack/sharing.md
+    - Registry server: cozy-apps-registry/README.md
 theme:
   custom_dir: cozy-theme
   name: material
@@ -65,8 +154,6 @@ theme:
   font:
     text: Lato
     code: Ubuntu Mono
-  feature:
-    tabs: true
 markdown_extensions:
 - admonition
 - codehilite
@@ -78,5 +165,57 @@ markdown_extensions:
 - toc:
     permalink: true
 extra:
+  outside_docs:
+  - name: cozy-app-publish
+    repo: https://github.com/cozy/cozy-app-publish.git
+    subdir: .
+  - name: cozy-apps-registry
+    repo: https://github.com/cozy/cozy-apps-registry.git
+    subdir: .
+  - name: cozy-client
+    repo: https://github.com/cozy/cozy-client.git
+    subdir: docs
+  - name: cozy-client-js
+    repo: https://github.com/cozy/cozy-client-js.git
+    subdir: docs
+  - name: cozy-ui
+    repo: https://github.com/cozy/cozy-ui.git
+    subdir: docs
+  - name: cozy-doctypes
+    repo: https://github.com/cozy/cozy-doctypes.git
+    subdir: .
+  - name: cozy-konnector-libs
+    repo: https://github.com/konnectors/libs.git
+    subdir: packages/cozy-konnector-libs/docs
+  - name: cozy-scripts
+    repo: https://github.com/cozy/create-cozy-app.git
+    subdir: packages/cozy-scripts/docs
+  - name: cozy-stack
+    repo: https://github.com/cozy/cozy-stack.git
+    subdir: docs
+  - name: konitor
+    repo: https://github.com/konnectors/konitor.git
+    subdir: docs
+  - name: babel-preset-cozy-app
+    repo: https://github.com/cozy/cozy-libs.git
+    subdir: packages/babel-preset-cozy-app
+  - name: commitlint-config-cozy
+    repo: https://github.com/cozy/cozy-libs.git
+    subdir: packages/commitlint-config-cozy
+  - name: cozy-device-helper
+    repo: https://github.com/cozy/cozy-libs.git
+    subdir: packages/cozy-device-helper
+  - name: eslint-config-cozy-app
+    repo: https://github.com/cozy/cozy-libs.git
+    subdir: packages/eslint-config-cozy-app
+  - name: cozy-flags
+    repo: https://github.com/cozy/cozy-libs.git
+    subdir: packages/cozy-flags
+  - name: cozy-realtime
+    repo: https://github.com/cozy/cozy-libs.git
+    subdir: packages/cozy-realtime
+  - name: ach
+    repo: https://github.com/cozy/ach.git
+    subdir: .
   search:
     tokenizer: "[^a-z\u0430-\u044F\u04510-9\\-\\.]"

mkdocs.yml.tpl

@@ -0,0 +1,83 @@
+site_name: Cozy Developer Documentation
+docs_dir: src
+site_url: https://docs.cozy.io/
+site_dir: docs/en
+site_favicon: img/favicon.png
+repo_url: https://github.com/cozy/cozy.github.io/
+edit_uri: edit/dev/src/
+site_description: Cozy documentation
+site_author: CozyCloud - https://cozy.io
+extra_css:
+- css/extra.css
+extra_javascript:
+- extra.js
+nav:
+- Home: index.md
+- Tutorials:
+  - Create Your Application: tutorials/app.md
+  - Develop a Connector:
+    - Introduction: tutorials/konnector/index.md
+    - Basic structure: tutorials/konnector/getting-started.md
+    - Scrape data: tutorials/konnector/scrape-data.md
+    - Save data: tutorials/konnector/save-data.md
+    - Package your connector: tutorials/konnector/packaging.md
+  - Self-Host on Debian: tutorials/selfhost-debian.md
+- How-to:
+  - Dev:
+    - Run an App in a Cozy using Docker: howTos/dev/runCozyDocker.md
+    - Use Hot Module Replacement in Your App: howTos/dev/hmr.md
+    - Make a Mobile App Using Cordova: howTos/dev/cordova.md
+    - Connect a Mobile App to Your Local Stack: howTos/dev/connect-mobile-app-local-stack.md
+    - Send and Receive E-mails in Development: howTos/dev/sendmail.md
+    - Our Front-End Git Flow: references/git-flow.md
+    - Technical introduction to the Cozy platform: references/tech-intro.md
+  - Synchronize:
+    - Install Cozy Drive on GNU/Linux: howTos/sync/linux.md
+- Libraries:
+  - Develop an application:
+    - Access data (client): <cozy-client>
+    - Build a UI (ui): <cozy-ui>
+    - Define data (doctypes): <cozy-doctypes>
+    - Advanced:
+      - Realtime data (realtime): <cozy-realtime>
+      - Native devices (device-helper): <cozy-device-helper>
+  - Develop a konnector:
+    - Scrape data (konnector-libs): <cozy-konnector-libs>
+    - konitor: <konitor>
+  - Publish on the store (app-publish): <cozy-app-publish>
+  - Dev tools:
+    - Babel preset: <babel-preset-cozy-app>
+    - Commitlint: <commitlint-config-cozy>
+    - ESLint: <eslint-config-cozy-app>
+    - ACH: <ach>
+  - Advanced:
+    - Stack server: <cozy-stack>
+    - Registry server: <cozy-apps-registry>
+- Applications:
+  - Cozy Banks: <cozy-banks>
+theme:
+  custom_dir: cozy-theme
+  name: material
+  palette:
+    primary: blue
+    accent: blue
+  logo:
+    icon: cloud
+  font:
+    text: Lato
+    code: Ubuntu Mono
+  feature:
+    tabs: true
+markdown_extensions:
+- admonition
+- codehilite
+- extra
+- footnotes
+- meta
+- sane_lists
+- smarty
+- toc:
+    permalink: true
+extra:
+  search:
+    tokenizer: "[^a-z\u0430-\u044F\u04510-9\\-\\.]"

serve.sh

@@ -1,4 +1,4 @@
 #!/bin/sh
 
-python add_external_docs.py
+python generate_config.py
 mkdocs serve