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

Already on GitHub? Sign in to your account

Doc edit link #496

Closed
wants to merge 2 commits into
from

Conversation

Projects
None yet
4 participants
Contributor

timmie commented Oct 4, 2012

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...

Owner

jseabold commented Oct 4, 2012

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.

Contributor

timmie commented Oct 4, 2012

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.

Owner

josef-pkt commented Oct 4, 2012

(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.

Contributor

timmie commented Oct 4, 2012

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.

Contributor

timmie commented Oct 4, 2012

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

Owner

josef-pkt commented Oct 4, 2012

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.)

Contributor

timmie commented Nov 5, 2012

Owner

jseabold commented Nov 13, 2012

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 Nov 14, 2012

Open

web editable docs #568

Owner

jseabold commented Nov 14, 2012

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

@jseabold jseabold closed this Nov 14, 2012

Contributor

timmie commented Mar 24, 2013

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?

Member

vincentarelbundock commented Mar 24, 2013

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