docs: replace doc with ref (close hasura#4054) (hasura#4068)

anurag · Mar 11, 2020 · e031e99 · e031e99
1 parent 315c399
commit e031e99
Show file tree

Hide file tree

Showing 152 changed files with 546 additions and 297 deletions.
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -104,6 +104,8 @@ without losing any visible quality.
 - Use bold in headings in place of string literals for aesthetics (i.e. ** in place of ``)
 - While adding code blocks ensure the right language type is set. Sometimes adding placeholders breaks the language's
 syntax in which case you'll have to set the language type to `none` to avoid warnings during builds.
+- Use `:ref:` instead of `:doc:` to link to pages to avoid having to set the relative path and chances of broken links
+while moving pages
 
 ### Pre-commit checks
 - Just before committing your changes, delete your local `_build` folder completely and then build docs again. Scan 

diff --git a/docs/graphql/manual/actions/action-connect.rst b/docs/graphql/manual/actions/action-connect.rst
@@ -2,6 +2,8 @@
    :description: Connecting Hasura actions with the graph
    :keywords: hasura, docs, actions, connect 
 
+.. _actions_connect:
+
 Connecting actions with the graph
 =================================
 

diff --git a/docs/graphql/manual/actions/action-handlers.rst b/docs/graphql/manual/actions/action-handlers.rst
@@ -2,6 +2,8 @@
    :description: Action handlers for Hasura actions
    :keywords: hasura, docs, actions, handlers
 
+.. _action_handlers:
+
 Action handlers
 ===============
 

diff --git a/docs/graphql/manual/actions/async-actions.rst b/docs/graphql/manual/actions/async-actions.rst
@@ -2,6 +2,8 @@
    :description: Async actions
    :keywords: hasura, docs, actions, async actions
 
+.. _async_actions:
+
 Async actions
 =============
 

diff --git a/docs/graphql/manual/actions/codegen.rst b/docs/graphql/manual/actions/codegen.rst
@@ -2,6 +2,8 @@
    :description: Codegen for Hasura actions
    :keywords: hasura, docs, actions, codegen
 
+.. _actions_codegen:
+
 Actions codegen
 ===============
 

diff --git a/docs/graphql/manual/actions/create.rst b/docs/graphql/manual/actions/create.rst
@@ -2,6 +2,8 @@
    :description: Creating Hasura actions
    :keywords: hasura, docs, actions, create 
 
+.. _create_actions:
+
 Creating actions
 ================
 

diff --git a/docs/graphql/manual/actions/derive.rst b/docs/graphql/manual/actions/derive.rst
@@ -2,6 +2,8 @@
    :description: Deriving Hasura actions
    :keywords: hasura, docs, actions, derive
 
+.. _derive_actions:
+
 Deriving actions
 ================
 

diff --git a/docs/graphql/manual/actions/index.rst b/docs/graphql/manual/actions/index.rst
@@ -2,6 +2,8 @@
    :description: Hasura actions
    :keywords: hasura, docs, actions
 
+.. _actions:
+
 Actions (beta)
 ==============
 
@@ -81,7 +83,7 @@ custom types like so:
       userId: Int!
     }
 
-Read more about :doc:`custom types<types/index>`.
+Read more about :ref:`custom types<custom_types>`.
 
 Handler
 *******
@@ -91,7 +93,7 @@ when the action mutation is executed. This can be done in an HTTP webhook,
 also called the action handler. It could be a REST endpoint or a serverless
 function.
 
-Learn more about :doc:`writing an action handler<action-handlers>`.
+Learn more about :ref:`writing an action handler<action_handlers>`.
 
 Kind
 ****
@@ -100,7 +102,7 @@ Actions are of two kinds:
 
 * **Synchronous actions**: Sync actions return a response to the client after
   receiving a response from the handler.
-* **Asynchronous actions**: :doc:`Async actions <async-actions>` return an
+* **Asynchronous actions**: :ref:`Async actions <async_actions>` return an
   ``action id`` as response to the client before receiving a response from the
   handler and allow the client to subscribe to the actual response using the
   ``action id``.

diff --git a/docs/graphql/manual/actions/types/index.rst b/docs/graphql/manual/actions/types/index.rst
@@ -2,6 +2,8 @@
    :description: Custom GraphQL types for Hasura actions
    :keywords: hasura, docs, actions, custom types
 
+.. _custom_types:
+
 Custom GraphQL types
 ====================
 

diff --git a/docs/graphql/manual/api-reference/config.rst b/docs/graphql/manual/api-reference/config.rst
@@ -66,4 +66,4 @@ the list of enabled APIs.
    --enabled-apis="graphql,metadata"
    HASURA_GRAPHQL_ENABLED_APIS="graphql,metadata"
 
-See :doc:`../deployment/graphql-engine-flags/reference` for info on setting the above flag/env var.
+See :ref:`server_flag_reference` for info on setting the above flag/env var.
diff --git a/docs/graphql/manual/api-reference/explain.rst b/docs/graphql/manual/api-reference/explain.rst
@@ -122,4 +122,4 @@ Sample response for a subscription
 Disabling Explain API
 ---------------------
 
-The Explain API is part of the :doc:`Metadata API <schema-metadata-api/index>` and can only be disabled by disabling the same.
+The Explain API is part of the :ref:`Metadata API <metadata_apis>` and can only be disabled by disabling the same.
diff --git a/docs/graphql/manual/api-reference/graphql-api/index.rst b/docs/graphql/manual/api-reference/graphql-api/index.rst
@@ -2,6 +2,8 @@
    :description: Hasura GraphQL API reference
    :keywords: hasura, docs, GraphQL API, reference
 
+.. _api_reference_graphql:
+
 GraphQL API Reference
 =====================
 
@@ -29,8 +31,8 @@ Request types
 
 The following types of requests can be made using the GraphQL API:
 
-- :doc:`Query / Subscription <query>`
-- :doc:`Mutation <mutation>`
+- :ref:`Query / Subscription <graphql_api_query>`
+- :ref:`Mutation <graphql_api_mutation>`
 
 Batching operations
 -------------------

diff --git a/docs/graphql/manual/api-reference/graphql-api/mutation.rst b/docs/graphql/manual/api-reference/graphql-api/mutation.rst
@@ -2,6 +2,8 @@
    :description: Hasura GraphQL API mutations API reference
    :keywords: hasura, docs, GraphQL API, API reference, mutation
 
+.. _graphql_api_mutation:
+
 API Reference - Mutation
 ========================
 
@@ -292,7 +294,7 @@ Delete syntax
 
 .. note::
 
-    For more examples and details of usage, please see :doc:`this <../../mutations/index>`.
+    For more examples and details of usage, please see :ref:`this <mutations>`.
 
 Syntax definitions
 ------------------

diff --git a/docs/graphql/manual/api-reference/graphql-api/query.rst b/docs/graphql/manual/api-reference/graphql-api/query.rst
@@ -2,6 +2,8 @@
    :description: Hasura GraphQL API queries and subscriptions API reference
    :keywords: hasura, docs, GraphQL API, API reference, query, subscription
 
+.. _graphql_api_query:
+
 API Reference - Query / Subscription
 ====================================
 
@@ -65,7 +67,7 @@ Query / subscription syntax
 
 .. note::
 
-    For more examples and details of usage, please see :doc:`this <../../queries/index>`.
+    For more examples and details of usage, please see :ref:`this <queries>`.
 
 Syntax definitions
 ------------------

diff --git a/docs/graphql/manual/api-reference/index.rst b/docs/graphql/manual/api-reference/index.rst
@@ -2,7 +2,7 @@
    :description: Hasura API reference
    :keywords: hasura, docs, API, API reference
 
-.. _api-reference:
+.. _api_reference:
 
 API Reference
 =============
@@ -42,7 +42,7 @@ GraphQL API
 
 All GraphQL requests for queries, subscriptions and mutations are made to the GraphQL API.
 
-See details at :doc:`graphql-api/index`.
+See details at :ref:`api_reference_graphql`.
 
 .. _schema_metadata_api:
 
@@ -54,7 +54,7 @@ executing SQL on the underlying Postgres.
 
 This is primarily intended to be used as an ``admin`` API to manage the Hasura schema and metadata.
 
-See details at :doc:`schema-metadata-api/index`.
+See details at :ref:`metadata_apis`.
 
 .. _version_api:
 
@@ -63,7 +63,7 @@ Version API
 
 The ``/v1/version`` is a public endpoint that responds with the current server version in JSON format.
 
-See details at :doc:`version`.
+See details at :ref:`version_api_reference`.
 
 .. _health_api:
 
@@ -72,7 +72,7 @@ Health check API
 
 The ``/healthz`` is a public endpoint that returns the server health status.
 
-See details at :doc:`health`.
+See details at :ref:`health_api_reference`.
 
 .. _pg_dump_api:
 
@@ -84,7 +84,7 @@ The ``/v1alpha1/pg_dump`` is an admin-only endpoint that can be used to execute
 tool's argument can be passed as a POST request body to the API and the response
 is sent back to the client.
 
-See details at :doc:`pgdump`.
+See details at :ref:`pg_dump_api_reference`.
 
 .. _config_api:
 
@@ -94,7 +94,7 @@ Config API
 ``v1alpha1/config`` is an admin-only endpoint to get the current server
 configuration.
 
-See details at :doc:`config`.
+See details at :ref:`config_api_reference`.
 
 .. _explain_api:
 
@@ -104,13 +104,13 @@ Explain API
 ``v1/graphql/explain`` returns the Postgres plan for a query or subscription based
 on the defined permissions.
 
-See details at :doc:`explain`.
+See details at :ref:`explain_api_reference`.
 
 Supported PostgreSQL types
 --------------------------
 You can refer to the following to know about all PostgreSQL types supported by the Hasura GraphQL engine:
 
-- :doc:`Supported PostgreSQL types <postgresql-types>`
+- :ref:`Supported PostgreSQL types <api_postgres_types>`
 
 .. toctree::
   :maxdepth: 1

diff --git a/docs/graphql/manual/api-reference/pgdump.rst b/docs/graphql/manual/api-reference/pgdump.rst
@@ -96,4 +96,4 @@ state that this API is not enabled. i.e. remove it from the list of enabled APIs
    --enabled-apis="graphql,metadata"
    HASURA_GRAPHQL_ENABLED_APIS="graphql,metadata"
 
-See :doc:`../deployment/graphql-engine-flags/reference` for info on setting the above flag/env var.
+See :ref:`server_flag_reference` for info on setting the above flag/env var.
diff --git a/docs/graphql/manual/api-reference/postgresql-types.rst b/docs/graphql/manual/api-reference/postgresql-types.rst
@@ -2,6 +2,8 @@
    :description: Supported PostgreSQL types in the Hasura API
    :keywords: hasura, docs, PostgreSQL types, API reference
 
+.. _api_postgres_types:
+
 API Reference - Supported PostgreSQL Types
 ==========================================
 

diff --git a/docs/graphql/manual/api-reference/schema-metadata-api/actions.rst b/docs/graphql/manual/api-reference/schema-metadata-api/actions.rst
@@ -2,6 +2,8 @@
    :description: Manage actions with the Hasura schema/metadata API
    :keywords: hasura, docs, schema/metadata API, API reference, actions
 
+.. _api_actions:
+
 Schema/Metadata API Reference: Actions
 ======================================
 
@@ -136,7 +138,7 @@ InputArgument
 
 .. note::
 
-   The ``GraphQL Types`` used in creating an action must be defined before via :doc:`Custom Types <custom-types>`
+   The ``GraphQL Types`` used in creating an action must be defined before via :ref:`Custom Types <api_custom_types>`
 
 .. _drop_action:
 

diff --git a/docs/graphql/manual/api-reference/schema-metadata-api/computed-field.rst b/docs/graphql/manual/api-reference/schema-metadata-api/computed-field.rst
@@ -2,6 +2,8 @@
    :description: Manage computed fields with the Hasura schema/metadata API
    :keywords: hasura, docs, schema/metadata API, API reference, computed field
 
+.. _api_computed_field:
+
 Schema/Metadata API Reference: Computed Fields
 ==============================================
 

diff --git a/docs/graphql/manual/api-reference/schema-metadata-api/custom-functions.rst b/docs/graphql/manual/api-reference/schema-metadata-api/custom-functions.rst
@@ -2,6 +2,8 @@
    :description: Manage custom functions with the Hasura schema/metadata API
    :keywords: hasura, docs, schema/metadata API, API reference, custom function
 
+.. _api_custom_functions:
+
 Schema/Metadata API Reference: Custom Functions
 ===============================================
 

diff --git a/docs/graphql/manual/api-reference/schema-metadata-api/custom-types.rst b/docs/graphql/manual/api-reference/schema-metadata-api/custom-types.rst
@@ -2,10 +2,12 @@
    :description: Define custom types with the Hasura schema/metadata API
    :keywords: hasura, docs, schema/metadata API, API reference, custom types
 
+.. _api_custom_types:
+
 Schema/Metadata API Reference: Custom Types
 ===========================================
 
-**Custom Types** are user-defined GraphQL types which help to define :doc:`Actions <actions>`.
+**Custom Types** are user-defined GraphQL types which help to define :ref:`Actions <api_actions>`.
 
 .. _set_custom_types:
 

diff --git a/docs/graphql/manual/api-reference/schema-metadata-api/event-triggers.rst b/docs/graphql/manual/api-reference/schema-metadata-api/event-triggers.rst
@@ -2,6 +2,8 @@
    :description: Manage event triggers with the Hasura schema/metadata API
    :keywords: hasura, docs, schema/metadata API, API reference, event trigger
 
+.. _api_event_triggers:
+
 Schema/Metadata API Reference: Event Triggers
 =============================================
 

diff --git a/docs/graphql/manual/api-reference/schema-metadata-api/index.rst b/docs/graphql/manual/api-reference/schema-metadata-api/index.rst
@@ -328,18 +328,18 @@ The various types of queries are listed in the following table:
 
 **See:**
 
-- :doc:`Run SQL <run-sql>`
-- :doc:`Tables/Views <table-view>`
-- :doc:`Custom SQL Functions <custom-functions>`
-- :doc:`Relationships <relationship>`
-- :doc:`Computed Fields <computed-field>`
-- :doc:`Permissions <permission>`
-- :doc:`Event Triggers <event-triggers>`
-- :doc:`Remote Schemas <remote-schemas>`
-- :doc:`Query Collections <query-collections>`
-- :doc:`Custom Types <custom-types>`
-- :doc:`Actions <actions>`
-- :doc:`Manage Metadata <manage-metadata>`
+- :ref:`Run SQL <api_run_sql>`
+- :ref:`Tables/Views <api_tables_views>`
+- :ref:`Custom SQL Functions <api_custom_functions>`
+- :ref:`Relationships <api_relationship>`
+- :ref:`Computed Fields <api_computed_field>`
+- :ref:`Permissions <api_permission>`
+- :ref:`Event Triggers <api_event_triggers>`
+- :ref:`Remote Schemas <api_remote_schemas>`
+- :ref:`Query Collections <api_query_collections>`
+- :ref:`Custom Types <api_custom_types>`
+- :ref:`Actions <api_actions>`
+- :ref:`Manage Metadata <api_manage_metadata>`
 
 Response structure
 ------------------
@@ -408,7 +408,7 @@ to explicitly state that this API is not enabled i.e. remove it from the list of
    --enabled-apis="graphql"
    HASURA_GRAPHQL_ENABLED_APIS="graphql"
 
-See :doc:`../../deployment/graphql-engine-flags/reference` for info on setting the above flag/env var.
+See :ref:`server_flag_reference` for info on setting the above flag/env var.
 
 .. toctree::
   :maxdepth: 1

diff --git a/docs/graphql/manual/api-reference/schema-metadata-api/manage-metadata.rst b/docs/graphql/manual/api-reference/schema-metadata-api/manage-metadata.rst
@@ -2,6 +2,8 @@
    :description: Manage metadata with the Hasura schema/metadata API
    :keywords: hasura, docs, schema/metadata API, API reference, metadata
 
+.. _api_manage_metadata:
+
 Schema/Metadata API Reference: Manage metadata
 ==============================================
 

diff --git a/docs/graphql/manual/api-reference/schema-metadata-api/permission.rst b/docs/graphql/manual/api-reference/schema-metadata-api/permission.rst
@@ -2,6 +2,8 @@
    :description: Manage permissions with the Hasura schema/metadata API
    :keywords: hasura, docs, schema/metadata API, API reference, permission
 
+.. _api_permission:
+
 Schema/Metadata API Reference: Permissions
 ==========================================
 

diff --git a/docs/graphql/manual/api-reference/schema-metadata-api/query-collections.rst b/docs/graphql/manual/api-reference/schema-metadata-api/query-collections.rst
@@ -2,6 +2,8 @@
    :description: Manage query collections with the Hasura schema/metadata API
    :keywords: hasura, docs, schema/metadata API, API reference, query collection
 
+.. _api_query_collections:
+
 Schema/Metadata API Reference: Query collections
 ================================================