Re: [PU Branch] Documentation with Sphinx
On Wed, 26 Mar 2014, Graham R. Armstrong wrote: Having gotten the API for Matcher in place, I'm wondering how we're planning to collect together documentation for PU. For APIs, the rough plan was to document methods inside restful files using rst docstrings, and then the overall machinery would collect and build the complete API docs out of these per-module inline docs. Best regards -- Tibor Simko
Re: [PU Branch] Documentation with Sphinx
(Sorry for double posting - sent from wrong e-mail) Right now the docs seems to just be listed all in one page (see for example api.rst) without a detailed index or toc. This happens when we add the automodule syntax in the api.rst or modules.rst files. This will get messy as soon as all the other modules are added here. Will module level documentation be automatically collected without being listed in these files? If so, where would we find it? One of the things that would be nice to have is a page per module, for example with everything you need to know about tags module. This page may then even have another hierarchy of docs below detailing high to low level APIs, admin/CLI manuals etc. Overall, though, this new documentation scheme looks promising and we are ready to help shape it further :-) Cheers, Jan Cheers, Jan --- Jan Age Lavik System Developer INSPIRE-HEP http://inspirehep.net Github: @jalavik https://github.com/jalavik Work phone: +41 22 76 78682 On Thu, Mar 27, 2014 at 10:38 AM, Jan Åge Lavik jala...@gmail.com wrote: Right now the docs seems to just be listed all in one page (see for example api.rst) without a detailed index or toc. This happens when we add the automodule syntax in the api.rst or modules.rst files. This will get messy as soon as all the other modules are added here. Will module level documentation be automatically collected without being listed in these files? If so, where would we find it? One of the things that would be nice to have is a page per module, for example with everything you need to know about tags module. This page may then even have another hierarchy of docs below detailing high to low level APIs, admin/CLI manuals etc. Overall, though, this new documentation scheme looks promising and we are ready to help shape it further :-) Cheers, Jan On Thu, Mar 27, 2014 at 9:25 AM, Tibor Simko tibor.si...@cern.ch wrote: On Wed, 26 Mar 2014, Graham R. Armstrong wrote: Having gotten the API for Matcher in place, I'm wondering how we're planning to collect together documentation for PU. For APIs, the rough plan was to document methods inside restful files using rst docstrings, and then the overall machinery would collect and build the complete API docs out of these per-module inline docs. Best regards -- Tibor Simko
Re: [PU Branch] Documentation with Sphinx
That's what I'd like to see, Matcher has it's API available (once merged) which is what should be available to other parts of Invenio. API-per-module would be the sensible way to organise it, then underneath document the lower-level code docs. Thanks for the responses. Graham On 27/03/14 10:38, Jan Åge Lavik wrote: Right now the docs seems to just be listed all in one page (see for example api.rst) without a detailed index or toc. This happens when we add the automodule syntax in the api.rst or modules.rst files. This will get messy as soon as all the other modules are added here. Will module level documentation be automatically collected without being listed in these files? If so, where would we find it? One of the things that would be nice to have is a page per module, for example with everything you need to know about tags module. This page may then even have another hierarchy of docs below detailing high to low level APIs, admin/CLI manuals etc. Overall, though, this new documentation scheme looks promising and we are ready to help shape it further :-) Cheers, Jan On Thu, Mar 27, 2014 at 9:25 AM, Tibor Simko tibor.si...@cern.ch mailto:tibor.si...@cern.ch wrote: On Wed, 26 Mar 2014, Graham R. Armstrong wrote: Having gotten the API for Matcher in place, I'm wondering how we're planning to collect together documentation for PU. For APIs, the rough plan was to document methods inside restful files using rst docstrings, and then the overall machinery would collect and build the complete API docs out of these per-module inline docs. Best regards -- Tibor Simko
[pu jsonalchemy] Aggregation of several fields into now
Hey guys! I have a question about the aggregation of several fields into one. Taking the example of the authors, lets say I have two fields `_first_author` and `_additional_authors` and I want to aggregate then into `authors`. The common case, and the easiest, is when I have one `_first_author` and cero or more `_additional_authors`, in which case I just put a list with the authors (what else right? :-) The problem, or the question, comes when I don’t have a `_first_author` in which case I’m not sure about the content of the `authors` field, it could be i) only the list of `_additional_authors` or ii) `None` follow by the the list of `_additional_authors`. I think the second solution is the closest one to reality, the `None` express that the record doesn’t have a first author. And I also think that we could apply this solution for other cases where we have this kind of situation (like with the `110__` and `710__`). What do you think? Lars, as you have already pu in production, how do you deal with this problem? Cheers, -- Esteban J. G. Gabancho
Re: [pu jsonalchemy] Aggregation of several fields into now
Hi Esteban! With the None approach, it fear it can get confusing when iterating over all authors (or whatever other field) as one then get None into the mix. If one really wants to get the first author, maybe calling first_author (where first_author is a direct lookup to _first_author) is enough and then expecting a None or empty list is alright? I dunno, it seems to me that when asking for give me all the authors, None does not belong there with John Ellis. Cheers, Jan Cheers, Jan --- Jan Age Lavik System Developer INSPIRE-HEP http://inspirehep.net Github: @jalavik https://github.com/jalavik Work phone: +41 22 76 78682 On Thu, Mar 27, 2014 at 3:38 PM, Esteban Gabancho esteban.jose.garcia.gaban...@cern.ch wrote: Hey guys! I have a question about the aggregation of several fields into one. Taking the example of the authors, lets say I have two fields `_first_author` and `_additional_authors` and I want to aggregate then into `authors`. The common case, and the easiest, is when I have one `_first_author` and cero or more `_additional_authors`, in which case I just put a list with the authors (what else right? :-) The problem, or the question, comes when I don’t have a `_first_author` in which case I’m not sure about the content of the `authors` field, it could be i) only the list of `_additional_authors` or ii) `None` follow by the the list of `_additional_authors`. I think the second solution is the closest one to reality, the `None` express that the record doesn’t have a first author. And I also think that we could apply this solution for other cases where we have this kind of situation (like with the `110__` and `710__`). What do you think? Lars, as you have already pu in production, how do you deal with this problem? Cheers, -- Esteban J. G. Gabancho
Re: [pu jsonalchemy] Aggregation of several fields into now
On 27.03.2014 15:38, Esteban Gabancho wrote: Hi! I think the second solution is the closest one to reality, the `None` express that the record doesn’t have a first author. And I also think that we could apply this solution for other cases where we have this kind of situation (like with the `110__` and `710__`). What do you think? If I may: as a librarian you have a 100. You may not have a 700, but in case you have only one author it is 100 by definition. You always have to read Marc with the cataloging rulebook in mind. (AACR*, RAK, what have you.) Still one should handle a cataloguing error. -- Kind regards, Alexander Wagner Scientific Services / Scientific Publishing Central Library 52425 Juelich mail : a.wag...@fz-juelich.de phone: +49 2461 61-1586 Fax : +49 2461 61-6103 http://www.fz-juelich.de/zb/wp Forschungszentrum Juelich GmbH 52425 Juelich Sitz der Gesellschaft: Juelich Eingetragen im Handelsregister des Amtsgerichts Dueren Nr. HR B 3498 Vorsitzender des Aufsichtsrats: MinDir Dr. Karl Eugen Huthmacher Geschaeftsfuehrung: Prof. Dr. Achim Bachem (Vorsitzender), Karsten Beneke (stellv. Vorsitzender), Prof. Dr.-Ing. Harald Bolt, Prof. Dr. Sebastian M. Schmidt
Re: [pu jsonalchemy] Aggregation of several fields into now
Hello Alexander, Esteban et al, Alexander Wagner a.wag...@fz-juelich.de wrote: On 27.03.2014 15:38, Esteban Gabancho wrote: I think the second solution is the closest one to reality, the `None` express that the record doesn’t have a first author. And I also think that we could apply this solution for other cases where we have this kind of situation (like with the `110__` and `710__`). What do you think? If I may: as a librarian you have a 100. You may not have a 700, but in case you have only one author it is 100 by definition. [to the non librarians in the crowd; Alexander knows it already] Or a 110, or a 111, I'd like to remind. An author is not only a 100 (personal author), but it may be a corporate one (110) or a conference (111). And please, don't forget that any of those tags may have arbitrary values as indicators. Best regards, Ferran
Re: [pu jsonalchemy] Aggregation of several fields into now
On 27.03.2014 15:38, Esteban Gabancho wrote: Hey guys! I have a question about the aggregation of several fields into one. Taking the example of the authors, lets say I have two fields `_first_author` and `_additional_authors` and I want to aggregate then into `authors`. The common case, and the easiest, is when I have one `_first_author` and cero or more `_additional_authors`, in which case I just put a list with the authors (what else right? :-) The problem, or the question, comes when I don’t have a `_first_author` in which case I’m not sure about the content of the `authors` field, it could be i) only the list of `_additional_authors` or ii) `None` follow by the the list of `_additional_authors`. I think the second solution is the closest one to reality, the `None` express that the record doesn’t have a first author. And I also think that we could apply this solution for other cases where we have this kind of situation (like with the `110__` and `710__`). In Zenodo i'm just interested in the list of authors, and the first in the list is by definition the first author. The first author/additional authors are somehow an artifact of having to store in MARC as master format. I'm not sure what we would be the most appropriate solution. Cheers, Lars What do you think? Lars, as you have already pu in production, how do you deal with this problem? Cheers, -- Esteban J. G. Gabancho -- Lars Holm Nielsen CERN, IT Department, Collaboration Information Services http://zenodo.org | Tel: +41 22 76 79182 | Cel: +41 76 672 8927 smime.p7s Description: S/MIME Cryptographic Signature
Re: [pu jsonalchemy] Aggregation of several fields into now
Hi Jan! On 27 Mar 2014, at 16:02, Jan Åge Lavik jan.age.la...@cern.ch wrote: With the None approach, it fear it can get confusing when iterating over all authors (or whatever other field) as one then get None into the mix. If one really wants to get the first author, maybe calling first_author (where first_author is a direct lookup to _first_author) is enough and then expecting a None or empty list is alright? I dunno, it seems to me that when asking for give me all the authors, None does not belong there with John Ellis. I understand (and share) your opinion, currently in the templates we are just iterating over the full list of authors and maybe we should start using the other keys. Lets see what the others think about this, although this is something that each Invenio instance should do with their data model definition. Cheers, -- Esteban J. G. Gabancho
Re: [PU Branch] Documentation with Sphinx
Hello, Sphinx documentation project in Invenio was just proof-of-concept if we can replace our custom webdoc. If you have a proposal how to organize user/admin/developers documentation, please share your ideas. Thanks. Best regards, -- Jiří Kunčar On 27. 3. 2014, at 10:56, Graham R. Armstrong graham.richard.armstr...@cern.ch wrote: That's what I'd like to see, Matcher has it's API available (once merged) which is what should be available to other parts of Invenio. API-per-module would be the sensible way to organise it, then underneath document the lower-level code docs. Thanks for the responses. Graham On 27/03/14 10:38, Jan Åge Lavik wrote: Right now the docs seems to just be listed all in one page (see for example api.rst) without a detailed index or toc. This happens when we add the automodule syntax in the api.rst or modules.rst files. This will get messy as soon as all the other modules are added here. Will module level documentation be automatically collected without being listed in these files? If so, where would we find it? One of the things that would be nice to have is a page per module, for example with everything you need to know about tags module. This page may then even have another hierarchy of docs below detailing high to low level APIs, admin/CLI manuals etc. Overall, though, this new documentation scheme looks promising and we are ready to help shape it further :-) Cheers, Jan On Thu, Mar 27, 2014 at 9:25 AM, Tibor Simko tibor.si...@cern.ch wrote: On Wed, 26 Mar 2014, Graham R. Armstrong wrote: Having gotten the API for Matcher in place, I'm wondering how we're planning to collect together documentation for PU. For APIs, the rough plan was to document methods inside restful files using rst docstrings, and then the overall machinery would collect and build the complete API docs out of these per-module inline docs. Best regards -- Tibor Simko smime.p7s Description: S/MIME cryptographic signature
kwalitee.invenio-software.org
Dear (‘pu’) developers, in last weeks we have been experimenting with GitHub hook that checks your pull requests. In first round we focused on well formatted commit messages as described in: http://invenio-software.org/wiki/Tools/Git/Workflow#R2.Remarksoncommitlogmessages Please note that we don’t run any spell/grammar checker ;) Now we are experimenting with PEP8/Pyflakes checker for each python file in pull request. It’s *optional* but personally, I would be happy if you try to check your files before creating pull request: $ git diff --name-only pu.. | \ xargs pep8 --ignore=E123,E226,E24,E501,E265. In case you see too many issues and you are willing to help making the code “nicer” you can try to run `autopep8` (on your own risk). $ git status # please make sure your code is committed! $ git checkout -b pu-pep8-improvements $ git diff --name-only pu.. | xargs \ autopep8 --ignore E123 --ignore E226 --ignore E24 --ignore E501 \ --ignore E265 --range 20 9 --diff # see the proposed changes $ git diff --name-only pu.. | xargs \ autopep8 --ignore E123 --ignore E226 --ignore E24 --ignore E501 \ --ignore E265 --range 20 9 --in-place # check the result $ git diff --name-only pu.. | \ xargs pep8 --ignore=E123,E226,E24,E501,E265. # fix the rest and commit :) $ git add ... $ git commit -s … # make a pull request In case of problems or if you have any proposal please check: https://github.com/jirikuncar/invenio-kwalitee/issues Best regards, -- Jiří Kunčar Software Engineer CERN, IT Department, Digital Library Technology Section Office 513/1-014 Tel: +41 22 76 62526 Cel: +41 78 850 1517 smime.p7s Description: S/MIME cryptographic signature
Re: [pu jsonalchemy] Aggregation of several fields into now
Hi Lars! Be careful with this general simplified notion. In some areas of research author ordering can cause sort of religious wars. And I may also add that depending on the area of research, the question I want all my papers, but only those where I am the first author is /very/ common. Up to the notion my papers == only those where I am the first author == only those count at all. So, a destinction of 1xx/7xx (of course Ferran is right about the other fields) is really important as is the ordering field $b. -- Kind regards, Alexander Wagner Subject Specialist Central Library 52425 Juelich mail : a.wag...@fz-juelich.de phone: +49 2461 61-1586 Fax : +49 2461 61-6103 www.fz-juelich.de/zb/DE/zb-fi - Reply message - From: Lars Holm Nielsen lars.holm.niel...@cern.ch Date: Thu, Mar 27, 2014 17:08 Subject: [pu jsonalchemy] Aggregation of several fields into now To: Esteban Gabancho esteban.jose.garcia.gaban...@cern.ch Cc: project-invenio-devel (Invenio developers mailing-list) project-invenio-devel@cern.ch On 27.03.2014 15:38, Esteban Gabancho wrote: Hey guys! I have a question about the aggregation of several fields into one. Taking the example of the authors, lets say I have two fields `_first_author` and `_additional_authors` and I want to aggregate then into `authors`. The common case, and the easiest, is when I have one `_first_author` and cero or more `_additional_authors`, in which case I just put a list with the authors (what else right? :-) The problem, or the question, comes when I don’t have a `_first_author` in which case I’m not sure about the content of the `authors` field, it could be i) only the list of `_additional_authors` or ii) `None` follow by the the list of `_additional_authors`. I think the second solution is the closest one to reality, the `None` express that the record doesn’t have a first author. And I also think that we could apply this solution for other cases where we have this kind of situation (like with the `110__` and `710__`). In Zenodo i'm just interested in the list of authors, and the first in the list is by definition the first author. The first author/additional authors are somehow an artifact of having to store in MARC as master format. I'm not sure what we would be the most appropriate solution. Cheers, Lars What do you think? Lars, as you have already pu in production, how do you deal with this problem? Cheers, -- Esteban J. G. Gabancho -- Lars Holm Nielsen CERN, IT Department, Collaboration Information Services http://zenodo.org | Tel: +41 22 76 79182 | Cel: +41 76 672 8927 Forschungszentrum Juelich GmbH 52425 Juelich Sitz der Gesellschaft: Juelich Eingetragen im Handelsregister des Amtsgerichts Dueren Nr. HR B 3498 Vorsitzender des Aufsichtsrats: MinDir Dr. Karl Eugen Huthmacher Geschaeftsfuehrung: Prof. Dr. Achim Bachem (Vorsitzender), Karsten Beneke (stellv. Vorsitzender), Prof. Dr.-Ing. Harald Bolt, Prof. Dr. Sebastian M. Schmidt
Re: Information about invenio 2.0
On Thu, 27 Mar 2014, Millet, Klaas wrote: However on https://invenio-software.org/roadmap I don’t see tickets assigning these kind of issues and so I was wondering if there was somewhere more information about which issues get priority This is mostly because we've been thinking about changing our ticketing system. Issues related to stabilising pu branch are not really expressed in Trac, neither as tickets nor as roadmap. We'll try to speed up the selection of our new ticketing tool, so that the work on stabilising pu branch would become much more visible. Please stay tuned! Best regards -- Tibor Simko