Revise the project template README.md to bring it up to date

[stichbury]

Description

I've noticed that the project README.md is in need of an update. It mentions build-reqs which is to be deprecated, and it looks like it needs a few improvements for readability.

ALSO -- and this is a separate thought that occurs to me.
Maybe we should add a markdown file to the docs/source directory with explanation for using Sphinx.
So it could include the fullsphinx-build command to build docs and similar text like the list of dependencies and how to install them with pip.

If it's given as a markdown file in the project docs, it's kind of useful as a template to get the docs building, and can illustrate good practice in terms of writing markdown.

[Gundalai-Batkhuu]

Hi @stichbury. I've recently learned how to use sphinx. I can write a markdown file with explanation for using sphinx for building Kedro docs like you've mentioned above. Would it be useful?

[stichbury]

Thanks for this @Gundalai-Batkhuu

We do have some guidance here https://docs.kedro.org/en/stable/tutorial/package_a_project.html#add-documentation-to-a-kedro-project so it would not require too much work. I think it's a question of creating a README.md file inside docs/source and linking to the docs we already have, and perhaps also linking to the Kedro style guide inside this repo's wiki, as a useful resource. Finally, you could point to information about GitHub pages and ReadTheDocs as possible places to publish docs, and that should have it covered.

So no need to write about Sphinx directly. If you spot any bugs in our docs at https://docs.kedro.org/en/stable/tutorial/package_a_project.html#add-documentation-to-a-kedro-project then please do feel free to amend that content also.

[Gundalai-Batkhuu]

@stichbury I tried to run 'sphinx-build source output' inside the docs directory to build the docs but I got an error:

Failed to create list of (regex, reStructuredText link replacement) for class names and method names in docstrings. Error is:
No module named 'kedro_datasets'

What am I missing here?

[astrojuanlu]

What am I missing here?

You can do make build-docs, it will do everything for you. You're missing some dependencies.

[ankatiyar]

Completed in #3387