[WIP] Rewrite of old documentation #110

HubLot · 2015-12-14T13:47:03Z

I rewrite the old documentation, written in Markdown, which was in the doc folder.
Now, it's written with rest/sphinx and the files are in the doc-api.
Hence, all documentation is in one place.

I described the installation and the utilization of the library. The utilization still needs enhancements for the API part. Then, from the previous markdown files, I described each utilization of the command-line tools.

This should solve issue #87 and #101.

What is still left to do:

Update the global README
Enhance doc for utilization of the API (in utilization.rst): describe the API, put links to notebooks
Update the doc for PBclust once [WIP] K-means #106 is merged
Solve issue Document the limitation of the PDB and PDBx parsers #104
More description in the index page of the doc.
Enhance installation part
Cite MDAnalysis
Rename the folder to doc

Link to this PR's documentation: https://pbxplore-hub.readthedocs.org/en/doc/

HubLot · 2015-12-15T10:13:06Z

I set Read the Docs on my account so you can see the documentation of this PR.
Here the link: https://pbxplore-hub.readthedocs.org/en/doc/

jbarnoud · 2015-12-15T10:35:32Z

doc-api/source/installation.rst

+.. code-block:: bash
+
+    $ pip install pbxplore
+


There could be a word about how to install from the source. Also, most users got in trouble because of they lacked the permissions to install the package system wide. Maybe a word about --user and a link to virtualenv could help.

I agree about the install from the source, few words to clone the depot and install it.
But, I'm not really convinced about the --user and the virtualenv. These are "global" options/set up for all python packages so the user would know about it. The main message here is to tell the package is on Pypi.

Being on Pypi does not make user able to install a package system wide
without sudo. And you do not want users to mess with the system
site-package directory... It would be great to have a general doc to
link, but I could not find one.

On 15-12-15 12:02, Hub wrote:

In doc-api/source/installation.rst
#110 (comment):

Matplotlib <http://matplotlib.org/>_ >= 1.4.0

All ploting functions use `matplotlib` package.

Weblogo3 <http://weblogo.threeplusone.com/>_ [#]_

`Weblogo3` is required to create logo from PB sequences.

+Installing PBxplore
+-------------------
+
+Once dependencies installed, the most straightforward way is to use pip:
+
+.. code-block:: bash
+

$ pip install pbxplore

I agree about the install from the source, few words to clone the
depot and install it.
But, I'm not really convinced about the |--user| and the virtualenv.
These are "global" options/set up for all python packages so the user
would know about it. The main message here is to tell the package is
on Pypi

—
Reply to this email directly or view it on GitHub
https://github.com/pierrepo/PBxplore/pull/110/files#r47622700.

I agree but I thinks it's out of scope of our tools. A link to pip and virtualenv documentations to inform the user will be enough imho

It is not in the scope of the doc to give a full course on install. Yet, we want users to be able to install the package. What I saw so far is pip install .' followed an error about permissions. This is why I think a word about--user` is usefull.

It could be something like:

Once dependencies installed, the most straightforward way is to use pip:

$ pip install pbxplore

PBxplore can also be installed for the current user only with:

$ pip install --user pbxplore

See the documentation of pip for more information. You may also want to look at virtualenv.

Sounds good to me.
No need to give a course on pip neither on virtualenv.
Go straight to the point.

Seems reasonable

jbarnoud · 2015-12-15T10:42:57Z

Yeah! Looks great! I added a few inline comments. In addition it would be nice to have a bit more intro in the landing page to make the project more catchy.

jbarnoud · 2015-12-15T10:44:52Z

Also, it is not only the API doc anymore so the doc title should be changed on https://github.com/HubLot/PBxplore/blob/doc/doc-api/source/conf.py#L57. The doc-api directory could be renamed doc.

Change also the project name in the sphinx parameters.

HubLot · 2015-12-15T14:06:07Z

Okay, I pushed few commits regarding our conversation and updated the PR description to reflect the updates.

jbarnoud · 2015-12-15T14:12:53Z

In the index page, 'PBxplore' got repeated in each subtitle (my bad). It may not be necessary. It could be nice, though, to have the pages about command line tools grouped under a subtitle (why not 'Command line interface'?).

HubLot · 2015-12-18T14:30:45Z

Yep, I know. I plan to remove those and regroup all cookbooks into one subtitle. But I need to modify the ipython notebooks.
I prefer to let all the command lines tools in the menu (rather than grouped them under a subtitle) because I think it will be more clear for the user.

- Add description of Pbxplore - Add authors - Reorganize the TOC

HubLot · 2016-01-12T15:44:50Z

Hi, I re-organize the index file of the documentation. I described a little more PBxplore, add authors, enhances the TOC.

Let me know what you think.

jbarnoud · 2016-01-12T15:55:29Z

doc/source/index.rst

+    :align: center
+
+    Schematic representation of the sixteen protein blocks, labeled from *a* to *p*
+    (Creative commons CC-BY).


A link to the license would be useful. Also it would tell what CC license exactly we are talking about.

I plan to add it at the end of file after "Contact & Support". For now, it's MIT but I don't know if we settled on that :)

My comment was unclear. Obviously my edit arrived too late. I am talking
about the CC licence for the figure here. CC by-sa is not just one
license, there are several versions and international port of it. A link
would tell exactly what CC license we are talking about. Also, a CC
license always should come with a link.

On 12-01-16 16:59, Hub wrote:

In doc/source/index.rst
#110 (comment):

+====================================
+
+PBxplore is a suite of tools dedicated to Protein Block analysis.
+
+Protein Blocks (PBs) are structural prototypes defined by
+de Brevern <http://www.dsimb.inserm.fr/~debrevern/index.php>_ et al in 2000 [#]_.
+The 3-dimensional local structure of a protein backbone can be modelized as an 1-dimensional
+sequence of PBs.
+In principle, any conformation of any amino acid could be represented
+by one of the sixteen available Protein Blocks.
+
+.. figure:: img/PBs.jpg

:align: center

Schematic representation of the sixteen protein blocks, labeled from a to p

(Creative commons CC-BY).

I plan to add it at the end of file after "Contact & Support". For
now, it's MIT but I don't know if we settled on that :)

—
Reply to this email directly or view it on GitHub
https://github.com/pierrepo/PBxplore/pull/110/files#r49472744.

jbarnoud · 2016-01-12T15:57:01Z

I needed some time to get use to the change but it looks great !

pierrepo · 2016-01-12T16:29:34Z

I am not a big fan of rst doc but we don't have the choice here.
I agree with the link to CC license.
I guess MIT is fine by now for the code.

jbarnoud · 2016-01-12T16:32:14Z

Out of curiosity, what is it you do not like with rst doc?

On 12-01-16 17:29, Pierre Poulain wrote:

I am not a big fan of rst doc but we don't have the choice here.
I agree with the link to CC license.
I guess MIT is fine by now for the code.

—
Reply to this email directly or view it on GitHub
#110 (comment).

pierrepo · 2016-01-12T16:38:42Z

The way is handle links (to web sites and images) I guess ;-)

HubLot · 2016-01-12T16:39:41Z

I agree with the link to CC license.

Which one should I choose ? From my point of view, it seems the 4.0 is ok but I'm not an expert.

I guess MIT is fine by now for the code.

Okay, I'll add the licence.

pierrepo · 2016-01-12T16:40:47Z

For CC license: the lost recent one will fine.

HubLot · 2016-01-13T15:00:15Z

Okay, the last few commits:

add the licences
improve the documentation about the API. I detailed a little bit more the different sub-modules (see https://pbxplore-hub.readthedocs.org/en/doc/api_cookbook.html)
I updated the GitHub Readme (https://github.com/HubLot/PBxplore/tree/doc). It's more or less the same content as the index of the documentation. I left "Download" section but once it's on Pypi, it should be replace with a quick install setup.

There is still the issue #104 but I don't really know where to put the information and how to write it properly.

jbarnoud · 2016-01-13T16:31:30Z

doc/source/api_cookbook.rst

+for further information.
+
+
+.. note:: plotting function require `Matplotlib <http://matplotlib.org/>`_.


Should be 'Plotting functions' (plural and capital P).

HubLot · 2016-01-14T09:13:28Z

At this point, if you are satisfied with my modifications, the PR can be merged.
Documentation of clustering and Pypi availability can only be done once @jbarnoud 's PR is merged.

HubLot · 2016-01-19T09:07:52Z

@pierrepo is it good for you? Can you merge if so?

[WIP] Rewrite of old documentation

HubLot added 9 commits December 10, 2015 14:45

Doc for installation

e5d1ede

Doc for Protein Blocks

b954ce8

Doc for PBassign

1af1d56

Doc for PBcount

23ac5c9

Reference for Weblogo

a8d1ca4

Add Neq definition

ce47d9a

Doc for PBstat

dfc11e3

Doc for PBclust

ab13ca6

Remove old documentation written in Markdown

4c6a0aa

jbarnoud reviewed Dec 15, 2015
View reviewed changes

HubLot added 3 commits December 15, 2015 14:30

Enhances installation documentation

4b56907

Citation for MDAnalysis

268a6a0

Rename documentation folder.

0d9383c

Change also the project name in the sphinx parameters.

HubLot force-pushed the doc branch from 11f5ebe to 0d9383c Compare December 15, 2015 13:54

jbarnoud added the documentation label Dec 18, 2015

HubLot added 2 commits January 12, 2016 10:45

Rename notebook titles

2ac205f

Enhances the index file of the documentation.

4580fd7

- Add description of Pbxplore - Add authors - Reorganize the TOC

HubLot force-pushed the doc branch from 79a63bf to 4580fd7 Compare January 12, 2016 15:34

jbarnoud reviewed Jan 12, 2016
View reviewed changes

HubLot added 3 commits January 12, 2016 17:58

Add licenses

a39476b

Improve documentation about the API

d7325a4

Update global README

7d91c22

HubLot force-pushed the doc branch from 92e4de7 to 7d91c22 Compare January 13, 2016 14:43

jbarnoud reviewed Jan 13, 2016
View reviewed changes

fix typo

99ac048

pierrepo added a commit that referenced this pull request Jan 29, 2016

Merge pull request #110 from HubLot/doc

83cb722

[WIP] Rewrite of old documentation

pierrepo merged commit 83cb722 into pierrepo:master Jan 29, 2016

HubLot deleted the doc branch February 1, 2016 14:35

This was referenced Feb 2, 2016

Document the dependancies for the concerned functions #87

Closed

Update the install documentation #101

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP] Rewrite of old documentation #110

[WIP] Rewrite of old documentation #110

HubLot commented Dec 14, 2015

HubLot commented Dec 15, 2015

jbarnoud Dec 15, 2015

HubLot Dec 15, 2015

jbarnoud Dec 15, 2015

HubLot Dec 15, 2015

jbarnoud Dec 15, 2015

pierrepo Dec 15, 2015

HubLot Dec 15, 2015

jbarnoud commented Dec 15, 2015

jbarnoud commented Dec 15, 2015

HubLot commented Dec 15, 2015

jbarnoud commented Dec 15, 2015

HubLot commented Dec 18, 2015

HubLot commented Jan 12, 2016

jbarnoud Jan 12, 2016

HubLot Jan 12, 2016

jbarnoud Jan 12, 2016

jbarnoud commented Jan 12, 2016

pierrepo commented Jan 12, 2016

jbarnoud commented Jan 12, 2016

pierrepo commented Jan 12, 2016

HubLot commented Jan 12, 2016

pierrepo commented Jan 12, 2016

HubLot commented Jan 13, 2016

jbarnoud Jan 13, 2016

HubLot Jan 14, 2016

HubLot commented Jan 14, 2016

HubLot commented Jan 19, 2016

		for further information.


		.. note:: plotting function require `Matplotlib <http://matplotlib.org/>`_.

[WIP] Rewrite of old documentation #110

[WIP] Rewrite of old documentation #110

Conversation

HubLot commented Dec 14, 2015

HubLot commented Dec 15, 2015

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

jbarnoud commented Dec 15, 2015

jbarnoud commented Dec 15, 2015

HubLot commented Dec 15, 2015

jbarnoud commented Dec 15, 2015

HubLot commented Dec 18, 2015

HubLot commented Jan 12, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jbarnoud commented Jan 12, 2016

pierrepo commented Jan 12, 2016

jbarnoud commented Jan 12, 2016

pierrepo commented Jan 12, 2016

HubLot commented Jan 12, 2016

pierrepo commented Jan 12, 2016

HubLot commented Jan 13, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

HubLot commented Jan 14, 2016

HubLot commented Jan 19, 2016