Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Doc edit link #496

Closed
wants to merge 2 commits into from

4 participants

@timmie

Usually, one notices an error / idea for improvement while reading the docs during the actual coding.

So I though such small glitches could be fixed right-away.

Thus I added an edit link next to the show source link.

I still see one thing we need to improve but I do not know how:
What happens with the pages that are auto-generated by Sphinx?
Like the examples.

Can we prevent Sphinx from adding the respective link by using a conditional check?

Here, my knowledge of templating ends...

@jseabold
Owner

Interesting idea. I think, if possible, the example docs could link back to the actual scripts used to generate them. Otherwise, I'm pretty sure we can check if we're on an example page and display the link or not. There should be an example of this kind of conditional in the templates already.

@timmie

Otherwise, I'm pretty sure we can check if we're on an example page and display the link or not.
There should be an example of this kind of conditional in the templates already.

OK, please give me a pointer or hint. You are probably more familiar with the documentation structure.
I had this nice idea and I am pretty sure that it may set a good example for many libraries in the scipy stack.

@josef-pkt
Owner

(written mostly before you started to reply)

practical issues (since we don't have a proper doceditor like numpy and scipy):

What happens when someone tries to edit statsmodels master and doesn't have commit rights?

I don't really like that docedits go immediately into master
I tried a docedit myself, and it was immediately committed to master
589f9dd
I'd rather have pull requests for review and merge many docedits at once.

Most of the information is in the doc strings, and there it would be more useful to point to the actual source, as the numpy scipy doceditor does.

I don't know if it is possible to set up a separate branch with more liberal commit rights. Then we could get something closer to the numpy/scipy editor.

@timmie

OK, I leave it up to you.
There once was a GSoC project to make Sphinx web-editable. But I donno where this landed.

May intention was to bring a bit more comfort into the correction/editing.
The hope is that this would also make it easier to fix the small things which are usually not obvious.

@timmie

I don't really like that docedits go immediately into master
I'd rather have pull requests for review and merge many docedits at once.

They are usually pull requests:
3d11c38

81e665b

@josef-pkt
Owner

If the online docedits by non-committers get converted to pull requests, then I think it should be possible to get this to work.

It might be tricky to find the right place in the sphinx docs to inject the edit link. Given that sphinx is able to add a source link e.g. top right http://statsmodels.sourceforge.net/devel/generated/statsmodels.regression.linear_model.OLS.html#statsmodels.regression.linear_model.OLS
I guess it's possible to point to master for the devel docs.
(They would sometimes point to the wrong place, between a merge and the html doc rebuild, but should be most of the time stable.)

@jseabold
Owner

What do we think about this? I'm thinking we close the PR while I'm doing housekeeping, but open a ticket so this idea doesn't get lost. Explore the possibility of using pydocweb like numpy, etc. on the ticket.

@jseabold jseabold referenced this pull request
Open

web editable docs #568

@jseabold
Owner

Closing this. See #568 for the ticket filed for future improvements.

@jseabold jseabold closed this
@timmie

Please have a look at the left pane of this page:
https://hieroglyph.readthedocs.org/en/latest/index.html

there's a direct link to edit in github.
What do you say?

@vincentarelbundock
Collaborator

Looks cool, but it just gives me the option to fork. I would still need to clone, edit, push, pull request. Doesn't seem like this is much of a shortcut...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
Showing with 18 additions and 0 deletions.
  1. +18 −0 docs/themes/statsmodels/sourcelink.html
View
18 docs/themes/statsmodels/sourcelink.html
@@ -0,0 +1,18 @@
+{#
+ basic/sourcelink.html
+ ~~~~~~~~~~~~~~~~~~~~~
+
+ Sphinx sidebar template: "show source" link.
+
+ :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ :license: BSD, see LICENSE for details.
+#}
+{%- if show_source and has_source and sourcename %}
+ <h3>{{ _('This Page') }}</h3>
+ <ul class="this-page-menu">
+ <li><a href="{{ pathto('_sources/' + sourcename, true)|e }}"
+ rel="nofollow">{{ _('Show Source') }}</a></li>
+ <li><a href="{{ https://github.com/statsmodels/statsmodels/edit/master/docs/source/ + sourcename, true)|e }}"
+ rel="nofollow">{{ _('Edit / Correct on GitHub') }}</a></li>
+ </ul>
+{%- endif %}
Something went wrong with that request. Please try again.