Restructuring the documentation

[RosalynLP]

Addresses #1121

[voisey]

@RosalynLP, these docs are looking niiiiiiiiiiiiiiiice

[RosalynLP]

@RosalynLP, these docs are looking niiiiiiiiiiiiiiiice

We're getting there!

[RosalynLP]

I think this is ready now @Zaharid @wilsonmr @siranipour @tgiani would be great if some of you could have a look and see what you think, any more structural suggestions etc. Caveat is that we intend to have an overview of the code after "getting started" to explain very loosely how everything links together - see @wilsonmr was assigned this in #656.

Also fixing the search bar broke Travis...

[Zaharid]

@RosalynLP @voisey Could I trouble you for a high level summary of what changed? Looking at the diff is not particularly easy...

[Zaharid]

@RosalynLP the error travis gives is

Error: bad character '>' in package version dependency 'sphinx_rtd_theme'

Perhaps you meant 'sphinx_rtd_theme >0.5'

[RosalynLP]

@RosalynLP the error travis gives is

Error: bad character '>' in package version dependency 'sphinx_rtd_theme'

Perhaps you meant 'sphinx_rtd_theme >0.5'

Ok thank you!

[RosalynLP]

@Zaharid

What has changed

• Summaries have been added to each section where necessary, explaining what the section is about
• The docs for code have been moved ahead of the theory section as we think this is more important for the user
• vp guide has a new introduction and a "getting started" page explaining how to use vp on a v basic level, and the sections have been reordered and grouped together
• examples section of vp guide has new table listing all the examples runcards, what they do and the corresponding tutorial if necessary
• empty sections have been removed, e.g. Q&A, DGLAP collinear factorisation
• Documentation section has been renamed "adding to documentation" and put at the end
• Installing code 2 sections have been merged with explanations for when to do each one
• rules and PR reviewing guidelines merged together
• external code section moved out of getting started and below other code
• tutorials have been grouped together by purpose
• additional links have been added to point the user to the right sections
• the page width has been increased for readability of tables and NNPDF logo added
• some sections have been renamed to make it clearer what those bits of code do. We are open to suggestions for alternative names

Seee #1121 for a tick box list

[Zaharid]

As a comment n3fit/index.html seems somewhat out of date. Not sure where should I report that at this point.

[RosalynLP]

As a comment n3fit/index.html seems somewhat out of date. Not sure where should I report that at this point.

Here is as good a place as any. Do you mean rather than describing it as a new model blah blah blah we just say it is the fitting code

[Zaharid]

I'd just remove a lot of that indeed.

[RosalynLP]

@Zaharid lmk what you think of the last commit

[RosalynLP]

I'm not entirely happy with the n3fit section... it explains the methodology of n3fit but is not very helpful for someone trying to understand the code. And the readme here https://github.com/NNPDF/nnpdf/tree/master/n3fit/src/n3fit is out of date. I think we could do with some sections on code structure, explaining how it all fits together and what the different bits do, and update the readme. @scarlehoff what are your thoughts on this? I am happy to do it but it would be good to have your help to look over what I've written.

But I think this is part of a broader issue we need to address of explaining the general code structure. We have decided to do a brief overview (assigned to @wilsonmr) but maybe we need something more for n3fit and validphys especially.

[scarlehoff]

Sure, I'd be happy to help.
I should totally change/remove that readme, it's just the content of the PR when it was first merged...

[RosalynLP]

OK amazing, although that is definitely work for a different PR than this.