Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improved documentation #12

Merged
merged 2 commits into from
Jun 18, 2014
Merged

Improved documentation #12

merged 2 commits into from
Jun 18, 2014

Conversation

kaplun
Copy link
Member

@kaplun kaplun commented Jun 18, 2014

  • Improves documentation by re-arranging its structure and
    introducing full discussion about performance merit of
    intbitset.

Signed-off-by: Samuele Kaplun samuele.kaplun@cern.ch

@coveralls
Copy link

Coverage Status

Coverage remained the same when pulling c32b0952df5b15e24b862536f37435d5f20baa75 on kaplun:improved-documentation into 8f4d763 on inveniosoftware:master.

jirikuncar
jirikuncar reviewed Jun 18, 2014
View reviewed changes
docs/index.rst
@@ -1,18 +1,15 @@
Welcome to intbitset's documentation!
Welcome to ``intbitset``'s documentation!
=====================================
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

=========================================

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd call the document simply "intbitset", dropping "welcome...".

@coveralls
Copy link

Coverage Status

Coverage remained the same when pulling 03b54d5 on kaplun:improved-documentation into 8f4d763 on inveniosoftware:master.

@coveralls
Copy link

Coverage Status

Coverage remained the same when pulling 7d93d50 on kaplun:improved-documentation into 8f4d763 on inveniosoftware:master.

@coveralls
Copy link

Coverage Status

Coverage remained the same when pulling 7d93d50 on kaplun:improved-documentation into 8f4d763 on inveniosoftware:master.

@jirikuncar jirikuncar added this to the v2.2 milestone Jun 18, 2014
tiborsimko
tiborsimko reviewed Jun 18, 2014
View reviewed changes
README.rst
and Python C extension to optimize speed and memory usage.
and *Python C extension* to optimize speed and memory usage.

On modern CPUs, *vectorial instruction sets* will be exploited to further optimize speed.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is kind of detail that belongs to the Note section where we speak about maxelem and stuff. It would be good if the beginning of the documentation is impactful. (I'll comment elsewhere on the structure.)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wanted to keep it in the README because it's what appears on Github, and on the Pypi. Somehow wanted to make further advertisement to intbitset.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, but vectorial instruction set or not is a kind of "detail" that may be put to note, not to the ABOUT overview, to keep it short. The numbers from the PERFORMANCE section speak about themselves... (BTW the future tense "will be exploited" may indicate this is not done yet...)

@tiborsimko
Copy link
Member

In addition to the above inline comments, one comment to the structure where it would be good to clearly separate usage section from performance section (that is kinda long):

intbitset

ABOUT

intbitset provides ...  (short paragraph with high-level overview)

USAGE

Example:

  x = intbitset([1,2,3])

Notes:
  - maxelem
  - endiannes

PERFORMANCE

Let us compare...  (long paragraph about numbers)

CONTENTS -> call it REFERENCE or API or something

class ...
   def...

CONTRIBUTING

CHANGELOG

LICENSE

Another thing is that on rtfd only contributing, changelog and license are separated in chapters; would be good to either separate others or include others, so that the overall table of contents would look nice. (following all ABOUT -> USAGE -> PERFORMANCE -> REFERENCE -> ... -> LICENSE chain)

@kaplun
Improved documentation
07a2c35 
* Improves documentation by re-arranging its structure and
  introducing full discussion about performance merit of
  intbitset.

* Overall, amends documentation to be compatible with
  reStructuredText.
  (closes inveniosoftware-contrib#8)

Signed-off-by: Samuele Kaplun <samuele.kaplun@cern.ch>
@kaplun
Classifiers for Python 2 and 3
f8c43bc 
* Adds generic classifiers for Python 2 and 3, so that
  intbitset can e.g. show up in:
  <https://pypi.python.org/pypi?:action=browse&c=533>

Signed-off-by: Samuele Kaplun <samuele.kaplun@cern.ch>
@kaplun kaplun changed the title WIP-Improved documentation Improved documentation Jun 18, 2014
kaplun added a commit that referenced this pull request Jun 18, 2014
@kaplun
Merge pull request #12 from kaplun/improved-documentation
68a4b79 
Improved documentation
@kaplun kaplun merged commit 68a4b79 into inveniosoftware-contrib:master Jun 18, 2014
@kaplun kaplun deleted the improved-documentation branch June 18, 2014 14:35
jirikuncar
jirikuncar reviewed Jun 25, 2014
View reviewed changes
src/intbitset.pyx
@@ -639,7 +614,7 @@ cdef class intbitset:
cpdef pop(intbitset self):
"""Remove and return an arbitrary set element.

@note: intbitset implementation of .pop() differs from the native C{set}
Note: intbitset implementation of .pop() differs from the native ``set``
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can use http://sphinx-doc.org/markup/para.html#directive-note

@tiborsimko
Copy link
Member

Another thing is that on rtfd only contributing, changelog and license are separated in chapters; would be good to either separate others or include others, so that the overall table of contents would look nice. (following all ABOUT -> USAGE -> PERFORMANCE -> REFERENCE -> ... -> LICENSE chain)

@kaplun Can you please look at this? Stil only Contributing, Changelog and License are singled out as chapters.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
Type: enhancement
Projects
None yet
Milestone
v2.2
Development

Successfully merging this pull request may close these issues.

None yet
4 participants
@kaplun @coveralls @tiborsimko @jirikuncar