From 065ace91ff047ee4bbceb16086ab2d97da9be7f0 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Thu, 9 Feb 2023 16:09:07 +0000 Subject: [PATCH 1/9] Update ahead of build-docs deprecation to remove mention of command Signed-off-by: Jo Stichbury --- docs/source/development/set_up_pycharm.md | 2 +- docs/source/tutorial/package_a_project.md | 17 ++++++++--------- 2 files changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/source/development/set_up_pycharm.md b/docs/source/development/set_up_pycharm.md index b2b9e62db0..a18bb9ff12 100644 --- a/docs/source/development/set_up_pycharm.md +++ b/docs/source/development/set_up_pycharm.md @@ -40,7 +40,7 @@ Finally, in the **Project Explorer** right-click on `src` and then go to **Mark [PyCharm Run configurations](https://www.jetbrains.com/help/pycharm/creating-run-debug-configuration-for-tests.html) allow you to execute preconfigured scripts rapidly in your IDE with a click of a button. This may be useful for testing, running and packaging your Kedro projects. -Here we will walk you through an example of how to setup Run configuration for Kedro CLI `run` command, however it is also applicable to other Kedro commands: `test`, `install`, `package`, `build-docs`. +Here we will walk you through an example of how to set up Run configuration for the Kedro CLI `run` command. It is also applicable to other Kedro commands, such as `test` or `install`. Go to **Run | Edit Configurations**: diff --git a/docs/source/tutorial/package_a_project.md b/docs/source/tutorial/package_a_project.md index e9eea49f8f..d6a4f3adde 100644 --- a/docs/source/tutorial/package_a_project.md +++ b/docs/source/tutorial/package_a_project.md @@ -7,22 +7,21 @@ Kedro also has an advanced feature which supports packaging on a pipeline level ## Add documentation to your project -Kedro uses the [Sphinx framework](https://www.sphinx-doc.org) and creates a `docs` directory that builds a basic template for project-specific documentation. We recommend that you add your project-specific documentation as markdown in `docs/source` +Kedro uses the [Sphinx framework](https://www.sphinx-doc.org) to build markdown documentation that you create about your project, in combination with any [`docstrings`](https://datacamp.com/community/tutorials/docstrings-python) that are defined in your code. -If you want to customise your documentation beyond the basic template, refer to the [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/configuration.html) for details of how to extend `docs/source/conf.py`. +Within the Kedro project structure there is a `docs` directory for Sphinx configuration files and to store project-specific markdown documentation. -Once you have added any documentation you need, run the following from the project root directory: +Add the documentation you need, and update `docs/source/index.rst` to define a table of contents + +Next, run the following from the project root directory: ```bash -kedro build-docs --open +sphinx-build -M html docs/source docs/build -a ``` -The HTML documention is built to `docs/build/html` and opens automatically in a browser tab. - -```{note} -The `build-docs` command creates documentation based on the code structure of your project. Documentation includes any [`docstrings`](https://datacamp.com/community/tutorials/docstrings-python) defined in your code. -``` +The command is configured to build the documentation as HTML, taking `docs/source` as the `sourcedir` and `/docs/build` as the `outputdir`. +Consult the Sphinx project documentation for [additional options to pass to `sphinx-build`](https://www.sphinx-doc.org/en/master/man/sphinx-build.html). To customise your documentation beyond the basic template, you'll need to adjust the [Sphinx configuration settings](https://www.sphinx-doc.org/en/master/usage/configuration.html) which are stored in `docs/source/conf.py` file. ## Package your project From 3e6b83346b5b0a06e1c79c6747c9e6a52fca48ed Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Thu, 9 Feb 2023 16:16:33 +0000 Subject: [PATCH 2/9] Minor tweak to experiment tracking doc to remove non-sequential header level H1->H3 Signed-off-by: Jo Stichbury --- docs/source/visualisation/experiment_tracking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/visualisation/experiment_tracking.md b/docs/source/visualisation/experiment_tracking.md index 54978da4a0..b372ad389b 100644 --- a/docs/source/visualisation/experiment_tracking.md +++ b/docs/source/visualisation/experiment_tracking.md @@ -11,7 +11,7 @@ The metadata you store may include: * Model weights * Plots and other visualisations -### Experiment tracking demonstration using Kedro-Viz +## Experiment tracking demonstration using Kedro-Viz We have made an [experiment tracking demo](https://demo.kedro.org/experiment-tracking) to enable you to explore the capabilities of Kedro-Viz further. From 661a05b48b05484af22b55c377475cb47a55746d Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Mon, 13 Feb 2023 14:20:03 +0000 Subject: [PATCH 3/9] Update to include sphinx-quickstart Signed-off-by: Jo Stichbury --- docs/source/tutorial/package_a_project.md | 71 ++++++++++++++++++++--- 1 file changed, 64 insertions(+), 7 deletions(-) diff --git a/docs/source/tutorial/package_a_project.md b/docs/source/tutorial/package_a_project.md index d6a4f3adde..fa62d11553 100644 --- a/docs/source/tutorial/package_a_project.md +++ b/docs/source/tutorial/package_a_project.md @@ -4,24 +4,81 @@ This section explains how to build your project documentation, and how to bundle Kedro also has an advanced feature which supports packaging on a pipeline level allowing you share and reuse pipelines across projects! To read more about this please look at the [section on micro-packaging](../nodes_and_pipelines/micro_packaging.md). - ## Add documentation to your project -Kedro uses the [Sphinx framework](https://www.sphinx-doc.org) to build markdown documentation that you create about your project, in combination with any [`docstrings`](https://datacamp.com/community/tutorials/docstrings-python) that are defined in your code. +Kedro uses the [Sphinx framework](https://www.sphinx-doc.org) to build markdown documentation that you create about your project. -Within the Kedro project structure there is a `docs` directory for Sphinx configuration files and to store project-specific markdown documentation. +Run the following from the project root directory: -Add the documentation you need, and update `docs/source/index.rst` to define a table of contents +```bash +pip install sphinx +``` -Next, run the following from the project root directory: +### Set up the Sphinx project files +Navigate to the `docs` directory of your Kedro project. Before Kedro version 0.19, this directory was pre-populated with Sphinx configuration files `conf.py`, and `index.rst` which the original `kedro build-docs` command needed. As that command is deprecated, if those files have been created with your Kedro project you should delete them (they will be removed from Kedro version 0.19 onwards), leaving your project's `docs` directory empty. + +In the terminal, run the following command from the `docs` folder: ```bash -sphinx-build -M html docs/source docs/build -a +sphinx-quickstart ``` -The command is configured to build the documentation as HTML, taking `docs/source` as the `sourcedir` and `/docs/build` as the `outputdir`. +In the instructions below, we assume that you select `y` to separate the documentation configuration files from the source files, but you can choose either option safely. Enter any additional information that Sphinx requests such as the project name and the documentation language (which defaults to English). + + +### Build HTML documentation +When the quickstart process is complete, run the following from the `docs` directory to build project documentation: + +```bash +make html +``` + +Your documentation will be built within an `docs/build/html` directory. + +You may add project-specific markdown documentation within the `docs/source` folder of your Kedro project and update `docs/source/index.rst` to add it to the table of contents. + +### Documentation from docstrings +If you wish to add documentation built from [`docstrings`](https://datacamp.com/community/tutorials/docstrings-python) within your project, you need to make the following changes to the Sphinx configuration files found in the `docs/source` directory to use [automatic documentation generation from code](https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html). + +Add the following to the top of the `docs/source/conf.py` file: + +```python +import os +import sys + +sys.path.insert(0, os.path.abspath(os.path.join("..", "..", "src"))) +``` +Also in `conf.py`, Ensure that the `sphinx.ext.autodoc` and `sphinx.ext.autosummary` extensions are specified, and `autosummary_generate` is enabled: + +```python +extensions = ["sphinx.ext.autodoc", "sphinx.ext.autosummary"] +autosummary_generate = True +``` + +Finally, ensure that you include the autodoc modules in your build by creating a separate file called `api.rst` in `docs/source`. Replace `project_name` with the name of your project: + +```text + +.. autosummary:: + :toctree: generated + + +``` + +Finally, add this to `docs/src/index.rst` +```text +.. toctree:: + + api +``` + +You can now run `make html` from the `docs` folder to build a full set of documentation that automatically includes docstrings. + + +```{note} Consult the Sphinx project documentation for [additional options to pass to `sphinx-build`](https://www.sphinx-doc.org/en/master/man/sphinx-build.html). To customise your documentation beyond the basic template, you'll need to adjust the [Sphinx configuration settings](https://www.sphinx-doc.org/en/master/usage/configuration.html) which are stored in `docs/source/conf.py` file. +``` ## Package your project From c42165c9fb96a78efbe240c069e3526c83b36187 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Mon, 13 Feb 2023 17:19:29 +0000 Subject: [PATCH 4/9] Final update for readability Signed-off-by: Jo Stichbury --- docs/source/tutorial/package_a_project.md | 43 +++++++++++++++-------- 1 file changed, 29 insertions(+), 14 deletions(-) diff --git a/docs/source/tutorial/package_a_project.md b/docs/source/tutorial/package_a_project.md index fa62d11553..49eeef322b 100644 --- a/docs/source/tutorial/package_a_project.md +++ b/docs/source/tutorial/package_a_project.md @@ -6,41 +6,55 @@ Kedro also has an advanced feature which supports packaging on a pipeline level ## Add documentation to your project -Kedro uses the [Sphinx framework](https://www.sphinx-doc.org) to build markdown documentation that you create about your project. +Kedro uses the [Sphinx framework](https://www.sphinx-doc.org) to build any documentation that you create about your project. -Run the following from the project root directory: +To install a compatible version of Sphinx, run the following from the project root directory: ```bash pip install sphinx ``` ### Set up the Sphinx project files -Navigate to the `docs` directory of your Kedro project. Before Kedro version 0.19, this directory was pre-populated with Sphinx configuration files `conf.py`, and `index.rst` which the original `kedro build-docs` command needed. As that command is deprecated, if those files have been created with your Kedro project you should delete them (they will be removed from Kedro version 0.19 onwards), leaving your project's `docs` directory empty. +Navigate to the `docs` directory of your Kedro project. Before Kedro version 0.19, the `docs/source` subdirectory was pre-populated with two Sphinx configuration files (`conf.py`, and `index.rst`) which the `kedro build-docs` command needed. -In the terminal, run the following command from the `docs` folder: +From Kedro version 0.19 that command is deprecated, and those files will no longer exist. If you have used an earlier version of Kedro to create your project, and want to follow the following instructions to build the documentation without using `kedro build-docs`, you should delete the two files and the `source` subdirectory so that your project's `docs` directory is empty. + +Navigate to the empty `docs` directory in the terminal, and run the following command: ```bash sphinx-quickstart ``` -In the instructions below, we assume that you select `y` to separate the documentation configuration files from the source files, but you can choose either option safely. Enter any additional information that Sphinx requests such as the project name and the documentation language (which defaults to English). +Sphinx will ask a series of configuration questions. The first is as follows: + +```text +You have two options for placing the build directory for Sphinx output. +Either, you use a directory "_build" within the root path, +or you separate "source" and "build" directories within the root path. + +> Separate source and build directories (y/n)? [n]: +``` + +In the following instructions, we assume that you select `y` to separate the built files from the source files, but you can choose either option safely and continue to follow the process. + +Enter any additional information that Sphinx requests such as the project name and the documentation language (which defaults to English). ### Build HTML documentation -When the quickstart process is complete, run the following from the `docs` directory to build project documentation: +When the quickstart process is complete, you may add project-specific markdown documentation within the `docs/source` folder of your Kedro project and update `docs/source/index.rst` to add it to the table of contents. + +To build the documentation, run the following **from the `docs` directory**: ```bash make html ``` -Your documentation will be built within an `docs/build/html` directory. - -You may add project-specific markdown documentation within the `docs/source` folder of your Kedro project and update `docs/source/index.rst` to add it to the table of contents. +Your project documentation is built to the `docs/build/html` directory. ### Documentation from docstrings If you wish to add documentation built from [`docstrings`](https://datacamp.com/community/tutorials/docstrings-python) within your project, you need to make the following changes to the Sphinx configuration files found in the `docs/source` directory to use [automatic documentation generation from code](https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html). -Add the following to the top of the `docs/source/conf.py` file: +Add the following to the beginning of the `docs/source/conf.py` file: ```python import os @@ -49,14 +63,14 @@ import sys sys.path.insert(0, os.path.abspath(os.path.join("..", "..", "src"))) ``` -Also in `conf.py`, Ensure that the `sphinx.ext.autodoc` and `sphinx.ext.autosummary` extensions are specified, and `autosummary_generate` is enabled: +Also in `conf.py`, add the following to ensure that the `sphinx.ext.autodoc` and `sphinx.ext.autosummary` extensions are specified, and `autosummary_generate` is enabled: ```python extensions = ["sphinx.ext.autodoc", "sphinx.ext.autosummary"] autosummary_generate = True ``` -Finally, ensure that you include the autodoc modules in your build by creating a separate file called `api.rst` in `docs/source`. Replace `project_name` with the name of your project: +Finally, to ensure that you include the autodoc modules in your build, create a separate file called `api.rst` in `docs/source`. You must replace `project_name` with the name of your project: ```text @@ -66,14 +80,15 @@ Finally, ensure that you include the autodoc modules in your build by creating a ``` -Finally, add this to `docs/src/index.rst` +Add the new file to `docs/src/index.rst` to include the automatically built documentation in the table of contents: + ```text .. toctree:: api ``` -You can now run `make html` from the `docs` folder to build a full set of documentation that automatically includes docstrings. +**Run `make html` from the `docs` folder** to build a full set of documentation that automatically includes docstrings. ```{note} From 04cc3903ca5abc0f43c6e8d20e6ec7ce561a95d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= Date: Wed, 15 Feb 2023 13:29:55 +0100 Subject: [PATCH 5/9] Rework Sphinx instructions (#2322) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Put deprecation of `kedro build-docs` inside a warning admonition - Clarify role of existing files and avoid deletion of `docs/source` contents - Clarify that other documentation systems exist - Make Sphinx commands forward and backward compatible - Clarify steps for Markdown documentation - Replace autosummary by regular autodoc Co-authored-by: Juan Luis Cano Rodríguez --- docs/source/tutorial/package_a_project.md | 54 +++++++++-------------- 1 file changed, 21 insertions(+), 33 deletions(-) diff --git a/docs/source/tutorial/package_a_project.md b/docs/source/tutorial/package_a_project.md index 49eeef322b..b7362a0800 100644 --- a/docs/source/tutorial/package_a_project.md +++ b/docs/source/tutorial/package_a_project.md @@ -6,23 +6,23 @@ Kedro also has an advanced feature which supports packaging on a pipeline level ## Add documentation to your project -Kedro uses the [Sphinx framework](https://www.sphinx-doc.org) to build any documentation that you create about your project. +There are several documentation frameworks for Python projects, with [Sphinx](https://www.sphinx-doc.org) being among the most popular ones. You can leverage Sphinx to build the documentation of your Kedro project. -To install a compatible version of Sphinx, run the following from the project root directory: +To install Sphinx, run the following: ```bash pip install sphinx ``` ### Set up the Sphinx project files -Navigate to the `docs` directory of your Kedro project. Before Kedro version 0.19, the `docs/source` subdirectory was pre-populated with two Sphinx configuration files (`conf.py`, and `index.rst`) which the `kedro build-docs` command needed. -From Kedro version 0.19 that command is deprecated, and those files will no longer exist. If you have used an earlier version of Kedro to create your project, and want to follow the following instructions to build the documentation without using `kedro build-docs`, you should delete the two files and the `source` subdirectory so that your project's `docs` directory is empty. +.. warning:: + At the moment, Kedro projects are created with a `docs/source` subdirectory, which gets pre-populated with two Sphinx configuration files (`conf.py`, and `index.rst`), needed by the `kedro build-docs command`. This command is deprecated, and starting with Kedro 0.19, it will no longer exist. Before proceeding with these instructions, backup the contents of `docs/source/index.rst` and remove both `docs/source/conf.py` and `docs/source/index.rst`. -Navigate to the empty `docs` directory in the terminal, and run the following command: +First, run the following command: ```bash -sphinx-quickstart +sphinx-quickstart docs ``` Sphinx will ask a series of configuration questions. The first is as follows: @@ -35,57 +35,45 @@ or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/n)? [n]: ``` -In the following instructions, we assume that you select `y` to separate the built files from the source files, but you can choose either option safely and continue to follow the process. - -Enter any additional information that Sphinx requests such as the project name and the documentation language (which defaults to English). - +Select `y` to separate the built files from the source files, and enter any additional information that Sphinx requests such as the project name and the documentation language (which defaults to English). ### Build HTML documentation -When the quickstart process is complete, you may add project-specific markdown documentation within the `docs/source` folder of your Kedro project and update `docs/source/index.rst` to add it to the table of contents. -To build the documentation, run the following **from the `docs` directory**: +.. warning:: + If you had backed up the contents of `index.rst`, restore them before proceeding. + +After the quickstart process is complete, you can build the documentation by **navigating to the `docs` directory** and running the following: ```bash make html ``` -Your project documentation is built to the `docs/build/html` directory. +Your project documentation will be written to the `docs/build/html` directory. -### Documentation from docstrings -If you wish to add documentation built from [`docstrings`](https://datacamp.com/community/tutorials/docstrings-python) within your project, you need to make the following changes to the Sphinx configuration files found in the `docs/source` directory to use [automatic documentation generation from code](https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html). - -Add the following to the beginning of the `docs/source/conf.py` file: - -```python -import os -import sys +You may want to add project-specific Markdown documentation within the `docs/source` folder of your Kedro project. To be able to build it, follow `the introduction instructions of MyST-Parser `_ and update your `docs/source/index.rst` file to add your newly created documents to the table of contents. -sys.path.insert(0, os.path.abspath(os.path.join("..", "..", "src"))) -``` +### Documentation from docstrings +If you wish to add documentation built from [`docstrings`](https://datacamp.com/community/tutorials/docstrings-python) within your project, you need to make some changes to the Sphinx configuration files found in the `docs/source` directory to use [automatic documentation generation from code](https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html). -Also in `conf.py`, add the following to ensure that the `sphinx.ext.autodoc` and `sphinx.ext.autosummary` extensions are specified, and `autosummary_generate` is enabled: +In `conf.py`, add the following to ensure that the `sphinx.ext.autodoc` and `sphinx.ext.autosummary` extensions are specified, and `autosummary_generate` is enabled: ```python extensions = ["sphinx.ext.autodoc", "sphinx.ext.autosummary"] autosummary_generate = True ``` -Finally, to ensure that you include the autodoc modules in your build, create a separate file called `api.rst` in `docs/source`. You must replace `project_name` with the name of your project: - -```text - -.. autosummary:: - :toctree: generated +Finally, to ensure that you include the autodoc modules in your build, run the following command once: - +```bash +sphinx-apidoc --module-first -o docs/source ./src/ ``` -Add the new file to `docs/src/index.rst` to include the automatically built documentation in the table of contents: +This will generate a `docs/src/modules.rst` file, as well as other files containing references to your docstrings. To include those in your documentation, make sure your `docs/src/index.rst` has a `modules` entry in the table of contents: ```text .. toctree:: - api + modules ``` **Run `make html` from the `docs` folder** to build a full set of documentation that automatically includes docstrings. From 613f5f42b5d3ecb436e1290fdc7e4300434bfab9 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Wed, 15 Feb 2023 12:47:29 +0000 Subject: [PATCH 6/9] Few final tweaks to copy Signed-off-by: Jo Stichbury --- docs/source/tutorial/package_a_project.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/source/tutorial/package_a_project.md b/docs/source/tutorial/package_a_project.md index b7362a0800..f06b7159e1 100644 --- a/docs/source/tutorial/package_a_project.md +++ b/docs/source/tutorial/package_a_project.md @@ -6,7 +6,7 @@ Kedro also has an advanced feature which supports packaging on a pipeline level ## Add documentation to your project -There are several documentation frameworks for Python projects, with [Sphinx](https://www.sphinx-doc.org) being among the most popular ones. You can leverage Sphinx to build the documentation of your Kedro project. +There are several documentation frameworks for Python projects. This section describes how to use [Sphinx](https://www.sphinx-doc.org) to build the documentation of your Kedro project. To install Sphinx, run the following: @@ -16,8 +16,11 @@ pip install sphinx ### Set up the Sphinx project files -.. warning:: - At the moment, Kedro projects are created with a `docs/source` subdirectory, which gets pre-populated with two Sphinx configuration files (`conf.py`, and `index.rst`), needed by the `kedro build-docs command`. This command is deprecated, and starting with Kedro 0.19, it will no longer exist. Before proceeding with these instructions, backup the contents of `docs/source/index.rst` and remove both `docs/source/conf.py` and `docs/source/index.rst`. +```{warning} +Currently, Kedro projects are created with a `docs/source` subdirectory, which gets pre-populated with two Sphinx configuration files (`conf.py`, and `index.rst`), needed by the `kedro build-docs command`. This command is deprecated; it will be removed in Kedro version 0.19, along with those dummy files. + +Before proceeding with these instructions, back up the contents of `docs/source/index.rst` and remove both `docs/source/conf.py` and `docs/source/index.rst`. +``` First, run the following command: @@ -35,12 +38,13 @@ or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/n)? [n]: ``` -Select `y` to separate the built files from the source files, and enter any additional information that Sphinx requests such as the project name and the documentation language (which defaults to English). +Select `y` to separate the built files from the source files, and enter any additional information that Sphinx requests such as the project name and the documentation language, which defaults to English. ### Build HTML documentation -.. warning:: - If you had backed up the contents of `index.rst`, restore them before proceeding. +```{warning} +If you previously backed up the contents of `index.rst`, restore them before proceeding. +``` After the quickstart process is complete, you can build the documentation by **navigating to the `docs` directory** and running the following: @@ -50,7 +54,7 @@ make html Your project documentation will be written to the `docs/build/html` directory. -You may want to add project-specific Markdown documentation within the `docs/source` folder of your Kedro project. To be able to build it, follow `the introduction instructions of MyST-Parser `_ and update your `docs/source/index.rst` file to add your newly created documents to the table of contents. +You may want to add project-specific Markdown documentation within the `docs/source` folder of your Kedro project. To be able to build it, follow the [introduction instructions of MyST-Parser](https://myst-parser.readthedocs.io/en/stable/intro.html) and update your `docs/source/index.rst` file to add the markdown files to the table of contents. ### Documentation from docstrings If you wish to add documentation built from [`docstrings`](https://datacamp.com/community/tutorials/docstrings-python) within your project, you need to make some changes to the Sphinx configuration files found in the `docs/source` directory to use [automatic documentation generation from code](https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html). @@ -78,7 +82,6 @@ This will generate a `docs/src/modules.rst` file, as well as other files contain **Run `make html` from the `docs` folder** to build a full set of documentation that automatically includes docstrings. - ```{note} Consult the Sphinx project documentation for [additional options to pass to `sphinx-build`](https://www.sphinx-doc.org/en/master/man/sphinx-build.html). To customise your documentation beyond the basic template, you'll need to adjust the [Sphinx configuration settings](https://www.sphinx-doc.org/en/master/usage/configuration.html) which are stored in `docs/source/conf.py` file. ``` From de78066934636530382648d9d3ef34f102f4fe1b Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Wed, 15 Feb 2023 14:51:45 +0000 Subject: [PATCH 7/9] Final tweak to clarify folders and install dependencies Signed-off-by: Jo Stichbury --- docs/source/tutorial/package_a_project.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/source/tutorial/package_a_project.md b/docs/source/tutorial/package_a_project.md index f06b7159e1..e9aa0abcdd 100644 --- a/docs/source/tutorial/package_a_project.md +++ b/docs/source/tutorial/package_a_project.md @@ -66,10 +66,11 @@ extensions = ["sphinx.ext.autodoc", "sphinx.ext.autosummary"] autosummary_generate = True ``` -Finally, to ensure that you include the autodoc modules in your build, run the following command once: +Finally, to ensure that you include the autodoc modules in your build, run the following command once **from the `docs` folder**: ```bash -sphinx-apidoc --module-first -o docs/source ./src/ +sphinx-apidoc --module-first -o source ../src/ + ``` This will generate a `docs/src/modules.rst` file, as well as other files containing references to your docstrings. To include those in your documentation, make sure your `docs/src/index.rst` has a `modules` entry in the table of contents: @@ -80,7 +81,17 @@ This will generate a `docs/src/modules.rst` file, as well as other files contain modules ``` -**Run `make html` from the `docs` folder** to build a full set of documentation that automatically includes docstrings. +**From the `docs` folder** run the following: + +```text +pip install -e ../src +``` + +Finally, **from the `docs folder`**, run this command to build a full set of documentation that automatically includes docstrings: + +```text +make html +``` ```{note} Consult the Sphinx project documentation for [additional options to pass to `sphinx-build`](https://www.sphinx-doc.org/en/master/man/sphinx-build.html). To customise your documentation beyond the basic template, you'll need to adjust the [Sphinx configuration settings](https://www.sphinx-doc.org/en/master/usage/configuration.html) which are stored in `docs/source/conf.py` file. From 3f0a4767ed84bc144ca2ba2ae991a9b2bdc68c0d Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Wed, 15 Feb 2023 14:56:29 +0000 Subject: [PATCH 8/9] Update docs/source/tutorial/package_a_project.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Juan Luis Cano Rodríguez --- docs/source/tutorial/package_a_project.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/tutorial/package_a_project.md b/docs/source/tutorial/package_a_project.md index e9aa0abcdd..20e862191c 100644 --- a/docs/source/tutorial/package_a_project.md +++ b/docs/source/tutorial/package_a_project.md @@ -17,7 +17,7 @@ pip install sphinx ### Set up the Sphinx project files ```{warning} -Currently, Kedro projects are created with a `docs/source` subdirectory, which gets pre-populated with two Sphinx configuration files (`conf.py`, and `index.rst`), needed by the `kedro build-docs command`. This command is deprecated; it will be removed in Kedro version 0.19, along with those dummy files. +Currently, Kedro projects are created with a `docs/source` subdirectory, which gets pre-populated with two Sphinx configuration files (`conf.py`, and `index.rst`), needed by the `kedro build-docs` command. This command is deprecated; it will be removed in Kedro version 0.19, along with those dummy files. Before proceeding with these instructions, back up the contents of `docs/source/index.rst` and remove both `docs/source/conf.py` and `docs/source/index.rst`. ``` From 6a88839a39a3ccf98b42aa4cf28157b015535dc4 Mon Sep 17 00:00:00 2001 From: Jo Stichbury Date: Thu, 16 Feb 2023 09:54:56 +0000 Subject: [PATCH 9/9] Update docs/source/tutorial/package_a_project.md --- docs/source/tutorial/package_a_project.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/tutorial/package_a_project.md b/docs/source/tutorial/package_a_project.md index 20e862191c..3df7fbfea6 100644 --- a/docs/source/tutorial/package_a_project.md +++ b/docs/source/tutorial/package_a_project.md @@ -38,7 +38,7 @@ or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/n)? [n]: ``` -Select `y` to separate the built files from the source files, and enter any additional information that Sphinx requests such as the project name and the documentation language, which defaults to English. +Select `y` to separate the build files from the source files, and enter any additional information that Sphinx requests such as the project name and the documentation language, which defaults to English. ### Build HTML documentation