Improve documents #2257

nissy-dev · 2020-10-29T08:28:30Z

Motivation

The current documents are not readable. I think there are some problems.

First, the index.rst is too fat. I think the simpler the index pages is, the more people reads. Actually, the index page of many OSS is very simple.

Second, the TOC Tree is not good. The point is the order and the content.
About the order, the last TOC tree is the contribution guide, so it is difficult to recognize the contribution guide section. And then, I don't understand why the top of first TOC tree is Tutorial. We should put on the Installation at the top. Before trying to do tutorials, users basically need to install the package.
About the contents, some TOC Tree contents like Datasets, DataLoaders and Data classes are hard to recognize the difference for newcomers. Basically, the TOC Tree about API reference is too fat.

Third, it doesn't have local summaries (like https://lifesci.dgl.ai/api/utils.mols.html) or local contents (https://lifesci.dgl.ai/api/utils.splitters.html) through all API references. These are really helpful when users search the API which they want.

And, the all docs files are putted on docs. It is not easy to find the file we want to add docs in. Especially, requirements.txt and requirements.rst are really troublesome. Considering about increasing the documents in the future, I think we should reorganize the document directory.

You may feel these changes is trivial, but I believe it is necessary to repeat these these changes for a good document

What I did

Reorganize directory structure
- the current directory structure is the same as the standard structures like DGL-Life-sci or PyG.
- all rst files are moved to docs/source
- docs/source has get_started, development_guide and api_reference directories and files are moved to the appropriate directory.
Update conf.py
- Fix the configuration based on JAXChem and PyG
Update documents except API reference
- I add the many comments in this PR.

After merging this PR, I will make the PR about updating the API reference docs step by step.
I already have updated about data, splitters, transformers in this branch, https://github.com/nd-02110114/deepchem/tree/fix-api-docs-1

This reverts commit b23600e.

rbharath

Lots of changes here :). Let me know when this is ready for a review! I did a brief pass through, but it would be useful to have a top level listing of the changes this PR makes and the motivation for them

nissy-dev · 2020-10-30T14:28:21Z

README.md

@@ -30,7 +30,7 @@ materials science, quantum chemistry, and biology.

 ## Requirements

-DeepChem currently supports Python 3.5 through 3.7 and requires these packages on any condition.
+DeepChem currently supports Python 3.6 through 3.7 and requires these packages on any condition.


DeepChem officially tested only Python 3.6 and 3.7, so I fixed.

This isn't related to this PR, but I think with the latest RDKit DeepChem also works for 3.8. We need to add that into the test suite explicitly though

nissy-dev · 2020-10-30T14:31:25Z

docs/Makefile

@@ -5,8 +5,8 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
+SOURCEDIR     = source


I changed the entry directories. source is the most standard in many OSS.

Good cleanup!

nissy-dev · 2020-10-30T14:32:23Z

docs/requirements.txt

@@ -3,5 +3,4 @@ scikit-learn
 sphinx_rtd_theme
 tensorflow==2.3.0
 transformers
-xgboost


Currently, the GDBTModel doesn't depend on the xgboost package, so I removed.

nissy-dev · 2020-10-30T14:43:47Z

docs/source/development_guide/licence.rst

@@ -0,0 +1,20 @@
+Licensing and Commercial Uses


This content is moved from the original index.rst

nissy-dev · 2020-10-30T14:46:23Z

docs/source/get_started/examples.rst

@@ -1,7 +1,16 @@
 Examples


The main modification of this file is to fix the cross-reference links like load_sampl or MultitaskRegressor

nissy-dev · 2020-10-30T14:49:30Z

docs/source/get_started/tutorial.rst

@@ -0,0 +1,52 @@
+Tutorials


I seemed the previous tutorials is under construction.
I updates the contents by putting on the notebook links.

This expanded doctest tutorial is great! Hopefully it will provide people a nice inline code sample example for them to work with :)

nissy-dev · 2020-10-30T14:56:32Z

docs/source/index.rst

@@ -0,0 +1,136 @@
+The DeepChem Project


I modified two things.

Make index.rst simpler (I think the simpler the index pages is, the more people reads)

Move Licensing and Commercial Uses to development_guide section

Merge Getting Involved to About US section

Update the outline in the bottom of this file

nissy-dev · 2020-10-30T15:50:16Z

@rbharath
This is ready for reviews!

nissy-dev · 2020-10-30T16:28:45Z

docs/source/conf.py

-autosummary_generate = True
-autodoc_default_flags = ['members', 'inherited-members']
-numpydoc_class_members_toctree = False


autosummary_generate is not used in docs.

autodoc_default_flags is the deprecated api.

numpydoc_class_members_toctree is not needed because we don't use numpydoc extension.

Do we need numpydock_class_members_toctree to handle the fact that our docstrings are written in numpy style? If we don't need it, good to remove!

numpydock_class_members_toctree is only needed by using numpydoc extension. But, the current docs use sphinx.ext.napoleon for parsing Numpy style docstring instead of numpydoc. So, I think this option is not valid, not necessary.

rbharath

Did a first pass! I like the refactor in general. I have a few suggested tweaks

rbharath · 2020-10-30T22:35:50Z

README.md

@@ -30,7 +30,7 @@ materials science, quantum chemistry, and biology.

 ## Requirements

-DeepChem currently supports Python 3.5 through 3.7 and requires these packages on any condition.
+DeepChem currently supports Python 3.6 through 3.7 and requires these packages on any condition.


This isn't related to this PR, but I think with the latest RDKit DeepChem also works for 3.8. We need to add that into the test suite explicitly though

rbharath · 2020-10-30T22:36:03Z

docs/Makefile

@@ -5,8 +5,8 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
+SOURCEDIR     = source


Good cleanup!

rbharath · 2020-10-30T22:37:17Z

docs/source/conf.py

@@ -21,39 +25,60 @@
 author = 'deepchem-contributors'

 # The full version, including alpha/beta/rc tags
-release = '2.4.0rc'
+version = deepchem.__version__


This is nice! Makes it less buggy with an automatic update

rbharath · 2020-10-30T22:42:30Z

docs/source/conf.py

-autosummary_generate = True
-autodoc_default_flags = ['members', 'inherited-members']
-numpydoc_class_members_toctree = False


Do we need numpydock_class_members_toctree to handle the fact that our docstrings are written in numpy style? If we don't need it, good to remove!

rbharath · 2020-10-30T22:44:03Z

docs/source/conf.py



-# This code was borrowed from Numpy's doc-to-source linker.
+# Resolve function for the linkcode extension.


This looks cleaner than the existing line linker :)

rbharath · 2020-10-30T22:54:13Z

docs/source/index.rst

+RDKit is a soft requirement package, but many useful methods like
+molnet depend on it.
+
+.. code-block:: bash


Perhaps we should change the top level to the nightly build for now since the conda release is still at 2.3.0

I agreed! I'm fixing!

rbharath · 2020-10-30T22:56:07Z

docs/tutorial.rst

-
-
-
-Datasets


I think it's still useful to have a basic tutorial in the docs itself. Colab is a little more heavy weight and it can be nice to give people a very quick glimpse of DeepChem code. Let's add this back into the new tutorial file.

Ideally, we could expand this out so it's a self-contained micro-overview of all of DeepChem :)

it can be nice to give people a very quick glimpse of DeepChem code

I think so, too! I will go back the dataset tutorials and add featurizer, splitter and model sections.

nissy-dev · 2020-11-01T14:18:34Z

This is ready for a second review!

rbharath

The new tutorial looks really nice! I think this is almost ready to merge in. Have a minor comment in one link where a user id got pasted in but once that's fixed feel free to merge in

rbharath · 2020-11-02T20:46:52Z

docs/source/get_started/installation.rst

@@ -167,7 +167,7 @@ If you are using the Windows and the PowerShell:


 .. _`DeepChem Tutorials`: https://github.com/deepchem/deepchem/tree/master/examples/tutorials
-.. _`forum post`: https://forum.deepchem.io/t/getting-deepchem-running-in-colab/81
+.. _`forum post`: https://forum.deepchem.io/t/getting-deepchem-running-in-colab/81/7?u=nd-02110114


I think the copy paste here added in your user id which should be removed

Yes, this is a mistake. I fixed.

rbharath · 2020-11-02T20:48:00Z

docs/source/get_started/tutorial.rst

@@ -0,0 +1,52 @@
+Tutorials


This expanded doctest tutorial is great! Hopefully it will provide people a nice inline code sample example for them to work with :)

coveralls · 2020-11-03T05:38:00Z

Coverage increased (+0.03%) to 80.693% when pulling 4f26c4a on nd-02110114:fix-docs-build into d79c5ea on deepchem:master.

nissy-dev · 2020-11-03T10:07:38Z

I fixed the links and the CI passed. So, I merge in.

nissy-dev added 13 commits October 28, 2020 17:15

♻️ refactor docs

7bb480c

🐛 fix bug

d2005eb

🐛 fix docs dir

177e64d

🐛 fix bug

b23600e

🔧 fix config

9c509bb

📝 update docs for get started and development

d1667d7

🚧 wip fix api references

b7d4d7f

🔥 remove unused codes

90fff2b

🐛 small bug

69f3f1d

🐛 fix small

708fd66

🐛 fix requiremtns path

2f82ffa

Revert ":bug: fix bug"

0e9b9b7

This reverts commit b23600e.

🐛 fix bug

720d38b

rbharath reviewed Oct 30, 2020

View reviewed changes

nissy-dev mentioned this pull request Oct 30, 2020

Weekly updates nissy-dev/deepchem#3

Closed

nissy-dev added 2 commits October 30, 2020 16:51

Merge branch 'master' into fix-docs-build

823e1bf

🐛 fix small bug

34fa116

nissy-dev commented Oct 30, 2020

View reviewed changes

nissy-dev changed the title ~~[WIP] Improve documents~~ Improve documents Oct 30, 2020

nissy-dev commented Oct 30, 2020

View reviewed changes

rbharath mentioned this pull request Oct 30, 2020

Adding in scientist FAQ #2220

Merged

rbharath reviewed Oct 30, 2020

View reviewed changes

Merge branch 'master' into fix-docs-build

c1f2ddf

nissy-dev added 2 commits October 31, 2020 16:16

👌 fix for reveiw

e3c96d9

📝 update docs

aa7246e

rbharath approved these changes Nov 2, 2020

View reviewed changes

nissy-dev added 2 commits November 3, 2020 10:22

Merge branch 'master' into fix-docs-build

bfe78d0

✨ add test for tutorials docs

5116826

nissy-dev mentioned this pull request Nov 3, 2020

implements concordance_index for regression evaluation #2263

Merged

nissy-dev added 2 commits November 3, 2020 15:13

Merge branch 'master' into fix-docs-build

db5f786

🐛 fix doc test error

4f26c4a

nissy-dev merged commit 27a8ef1 into deepchem:master Nov 3, 2020

nissy-dev deleted the fix-docs-build branch November 3, 2020 14:01

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve documents #2257

Improve documents #2257

nissy-dev commented Oct 29, 2020 •

edited

Loading

rbharath left a comment

nissy-dev Oct 30, 2020

rbharath Oct 30, 2020

nissy-dev Oct 30, 2020 •

edited

Loading

rbharath Oct 30, 2020

nissy-dev Oct 30, 2020

nissy-dev Oct 30, 2020

nissy-dev Oct 30, 2020 •

edited

Loading

nissy-dev Oct 30, 2020

rbharath Nov 2, 2020

nissy-dev Oct 30, 2020 •

edited

Loading

nissy-dev commented Oct 30, 2020

nissy-dev Oct 30, 2020

rbharath Oct 30, 2020

nissy-dev Oct 31, 2020

rbharath left a comment

rbharath Oct 30, 2020

rbharath Oct 30, 2020

rbharath Oct 30, 2020

rbharath Oct 30, 2020

rbharath Oct 30, 2020

rbharath Oct 30, 2020

nissy-dev Oct 31, 2020

rbharath Oct 30, 2020

nissy-dev Oct 31, 2020

nissy-dev commented Nov 1, 2020

rbharath left a comment

rbharath Nov 2, 2020

nissy-dev Nov 3, 2020

rbharath Nov 2, 2020

coveralls commented Nov 3, 2020 •

edited

Loading

nissy-dev commented Nov 3, 2020



		# This code was borrowed from Numpy's doc-to-source linker.
		# Resolve function for the linkcode extension.




		Datasets

Improve documents #2257

Improve documents #2257

Conversation

nissy-dev commented Oct 29, 2020 • edited Loading

Motivation

What I did

rbharath left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nissy-dev Oct 30, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nissy-dev Oct 30, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nissy-dev Oct 30, 2020 • edited Loading

Choose a reason for hiding this comment

nissy-dev commented Oct 30, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rbharath left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nissy-dev commented Nov 1, 2020

rbharath left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

coveralls commented Nov 3, 2020 • edited Loading

nissy-dev commented Nov 3, 2020

nissy-dev commented Oct 29, 2020 •

edited

Loading

nissy-dev Oct 30, 2020 •

edited

Loading

nissy-dev Oct 30, 2020 •

edited

Loading

nissy-dev Oct 30, 2020 •

edited

Loading

coveralls commented Nov 3, 2020 •

edited

Loading