Updated README.md

docs/sphinx-doc/README.md

@@ -1,30 +1,71 @@
-### Sphinx-doc directory
+### Sphinx-doc
 
 This directory contains sources for building project documentation using Sphinx-doc.
 
 
 #### Requirements:
 
+All requirements can be installed in the conda environment `sphinx` from the file `environment.yml`:
+
+`conda env create -f docs/sphinx-doc/environment.yml`
+
+If you have this environment already and want to update it, run:
+
+`conda env update -f docs/sphinx-doc/environment.yml`
+
+Or you can install requirements manually:
+
 1. Install Sphinx-doc: 
- `conda install sphinx` or `pip install -U Sphinx`. 
+
+ `conda install sphinx` or `pip install -U Sphinx`. 
+
  Other ways: https://www.sphinx-doc.org/en/master/usage/installation.html
 
 2. Install `jupyter_sphinx` extension: `conda install jupyter_sphinx` or `pip install jupyter-sphinx`.
 
-3. All dependencies, used in your executable code inside the documents must be installed to your Python/Anaconda environment.
+3. All dependencies, used in your executable code inside the documents must be installed to your Python/Anaconda
+environment (see: `docs/sphinx-doc/environment.yml`).
 
 
 #### How to use:
 
 1. Create docs in `reStructuredText` format (files `*.rst`): 
  https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
 
-2. Put them in the `source` directory. Any additional directory can be created inside for the structure optimisation.
+2. Put them in the `docs/sphinx-doc/source` directory. Any additional directory can be created inside for the structure optimisation.
+
+3. Add paths to new docs in the `docs/sphinx-doc/source/index.rst` file.
+
+4. Build documentation (HTML): 
+
+ `sphinx-build -b html docs/sphinx-doc/source docs/sphinx-doc/build/`
+
+5. Open `docs/sphinx-doc/build/index.html` in your browser and check result.
+
+
+#### Using 'autodoc' generator:
+
+Autodoc generates documentation from Docstrings. Used with `napoleon` extension to parse NumPy docstrings.
+Project already has generated autodoc structure for current Python modules: `docs/sphinx-doc/source/autodoc`.
+
+1. To add a new module to the autodoc structure run:
+
+ `sphinx-apidoc -f -o docs/sphinx-doc/source/autodoc python-package/lets_plot/<path_to_module>`
+
+ New `*.rst` file with the module name will appear in the `docs/sphinx-doc/source/autodoc`.
+ Add the path to this file in the `docs/sphinx-doc/source/index.rst`.
+
+2. Edit docstrings in the `*.py` files of modules.
+
+3. Build `python-package` (set values in the `build_settings.yml` to use your `sphinx` environment): 
+
+ `./gradlew python-package-build:build`
+
+ Then install the package to your `sphinx` environment.
 
-3. Add paths to new docs in the `index.rst` file.
+4. Build documentation (HTML): 
 
-4. Build documentation (HTML): change dir to `docs/sphinx-doc` and execute the command: 
- `sphinx-build -b html source/ build/`
+ `sphinx-build -b html docs/sphinx-doc/source docs/sphinx-doc/build/`
 
 5. Open `docs/sphinx-doc/build/index.html` in your browser and check result.
 
@@ -34,8 +75,8 @@ This directory contains sources for building project documentation using Sphinx-
  - `source/` - main source folder
  - `source/conf.py` - main config file
  - `source/index.rst` - source file for index.html (main page with content tree and etc.)
- - `source/ref` - directory with current reference document sources.
- - `source/usage` - directory with current usage document sources. 
+ - `source/autodoc` - directory with the generated 'autodoc' structure files.
+ - `source/ref` and `source/usage` - directories with the examples of document sources.
  - `source/_static` and `source/_templates` - service directories (auto-generated). Can be used in the future.
  - `build/` - directory containing generated documentation as prepared structure. Will be added by executing `sphinx-build` command. **Ignored by Git.**
  - `jupyter-execute/` - directory generated by the `jupyter_sphinx` extension. Contains files `*.py` and `*.ipynb` (executed code from the documents sources). **Ignored by Git.**