Skip to content

"Improve this Doc" URL goes back to a 404 when canceling out #3156

Closed
Closed
"Improve this Doc" URL goes back to a 404 when canceling out#3156
Labels
templateThe stock site template

Description

@airbreather
airbreather
opened on Aug 4, 2018

DocFX Version Used: docfx.console 2.37.2

Template used: default

Steps to Reproduce:

  1. Write a .NET project on GitHub with at least one interesting member that can get an "Improve this Doc" link.
  2. Generate API documentation for that project.
  3. Browse the API documentation.
  4. Click an "Improve this Doc" link.
  5. Click the "Cancel" link near the top.

Expected Behavior:
You should be punted back to the overwrite directory that the file would have been created in, same as if you got to the "Create new file" page by clicking the button while browsing the overwrite directory on GitHub.

Actual Behavior:

It punts you back to a 404 page.

Live Sample:

https://nettopologysuite.github.io/NetTopologySuite.IO.GPX/api/NetTopologySuite.IO.GpxBoundingBox.html

  • For example, the "Improve this Doc" for the summary points me here, and canceling punts you back here, which is the 404 I'm referring to.

Activity

  1. airbreather commented on Aug 4, 2018

    @airbreather
    airbreather
    on Aug 4, 2018
    Author

    This may very well be a bug on GitHub's side, but I wanted to start here in case we think there's something we can do with the URL to make it work the way a user might expect it to.

  2. herohua
    added
    question
    on Aug 5, 2018

  3. herohua commented on Aug 5, 2018

    @herohua
    herohua
    on Aug 5, 2018
    Contributor

    @airbreather , I did not see a "Cancel" link on the page with the "Improve this Doc" link:
    image

    Could you provide more information?

  4. herohua
    added
    Area-Build
    and removed
    Area-Build
    on Aug 5, 2018
  5. herohua
    self-assigned this
    on Aug 5, 2018

  6. airbreather commented on Aug 5, 2018

    @airbreather
    airbreather
    on Aug 5, 2018
    Author

    Ahh -- it appears that I only immediately see "Cancel" when logged in as someone with push access to the repo!
    image

    The equivalent page shows up when you click "Fork this repository and propose changes", and the same thing happens when I click "Cancel" there... tested on some random page for docfx:
    image

    Specifically, that was FileMappingItem --> Improve this Doc, which should (for someone with push access to dotnet/docfx) give what I saw on mine, which should (I think) punt you back to this, which 404s.

  7. stale commented on Mar 6, 2019

    @stale
    staleBot
    on Mar 6, 2019

    This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.

  8. stale
    added
    stale
    on Mar 6, 2019

  9. airbreather commented on Mar 6, 2019

    @airbreather
    airbreather
    on Mar 6, 2019
    Author

    This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.

    Thank you, friendly bot, for doing your part to help keep repositories clean.

    This still appears to be an issue in the latest stable release (2.40.11).

  10. stale
    removed
    stale
    on Mar 6, 2019
  11. superyyrrzz
    removed
    question
    on Mar 20, 2019

  12. superyyrrzz commented on Mar 20, 2019

    @superyyrrzz
    superyyrrzz
    on Mar 20, 2019
    Contributor

    This should be a repo config issue. When you click cancel, GitHub will lead you back to the directory you just try creating. If it does not exist, it will be 404.

    To resolve this, you shall ensure the directory doc/overwrite/ exist in your repo. Of course, git does not support create an empty directory. You can add a placeholder file in it.

  13. airbreather commented on Mar 20, 2019

    @airbreather
    airbreather
    on Mar 20, 2019
    Author

    To resolve this, you shall ensure the directory doc/overwrite/ exist in your repo. Of course, git does not support create an empty directory. You can add a placeholder file in it.

    That doesn't seem to be enough, unfortunately. I do have a .gitkeep file here: https://github.com/NetTopologySuite/NetTopologySuite.IO.GPX/tree/master/doc/overwrite however, links such as this cancel back to this.

    It looks like the problem is that the links on pages such as this one use the following format:

    https://github.com/NetTopologySuite/NetTopologySuite.IO.GPX/new/master/doc/overwrite/new?filename=NetTopologySuite_IO_GpxBoundingBox.md&value=---%0Auid%3A%20NetTopologySuite.IO.GpxBoundingBox%0Asummary%3A%20%27*You%20can%20override%20summary%20for%20the%20API%20here%20using%20*MARKDOWN*%20syntax%27%0A---%0A%0A*Please%20type%20below%20more%20information%20about%20this%20API%3A*%0A%0A

    Which cancels back to:

    https://github.com/NetTopologySuite/NetTopologySuite.IO.GPX/tree/master/doc/overwrite/new

    When exploring around, I noticed that I can change overwrite/new?filename to overwrite/.gitkeep?filename, like so:

    https://github.com/NetTopologySuite/NetTopologySuite.IO.GPX/new/master/doc/overwrite/.gitkeep?filename=NetTopologySuite_IO_GpxBoundingBox.md&value=---%0Auid%3A%20NetTopologySuite.IO.GpxBoundingBox%0Asummary%3A%20%27*You%20can%20override%20summary%20for%20the%20API%20here%20using%20*MARKDOWN*%20syntax%27%0A---%0A%0A*Please%20type%20below%20more%20information%20about%20this%20API%3A*%0A%0A

    Then the "cancel" link puts me to the dummy file I created in my "overwrite" folder:

    https://github.com/NetTopologySuite/NetTopologySuite.IO.GPX/blob/master/doc/overwrite/.gitkeep

    I think this is probably a GitHub bug. Removing all the query parameters and the final "/new" gives me a link like this, which works exactly as I expect it to work (of course, without the special name and contents that docfx require in order for it to do what we're trying to do):

    https://github.com/NetTopologySuite/NetTopologySuite.IO.GPX/new/develop/doc/overwrite

    As soon as I add the "filename" query parameter, it seems to go up a level.

    I was able to manually come up with a URL that does work the way I wanted it to, however: changing overwrite/new?filename=whatWeGenerateNow to overwrite?filename=overwrite/whatWeGenerateNow like so:

    https://github.com/NetTopologySuite/NetTopologySuite.IO.GPX/new/master/doc/overwrite?filename=overwrite/NetTopologySuite_IO_GpxBoundingBox.md&value=---%0Auid%3A%20NetTopologySuite.IO.GpxBoundingBox%0Asummary%3A%20%27*You%20can%20override%20summary%20for%20the%20API%20here%20using%20*MARKDOWN*%20syntax%27%0A---%0A%0A*Please%20type%20below%20more%20information%20about%20this%20API%3A*%0A%0A

    Brings me to a page that works exactly as I expect it to.

  14. superyyrrzz commented on Mar 20, 2019

    @superyyrrzz
    superyyrrzz
    on Mar 20, 2019
    Contributor

    @airbreather Thank you for the experiments!

    As soon as I add the "filename" query parameter, it seems to go up a level.

    My investigation stuck here before. So I added the final /new to make it work. It is really interesting that duplicating overwrite can get a perfect URL! BTW, I also feel it like a GitHub bug.

    You can try customizing template to make it work. Welcome to contribute back 😄 Related code:

    docfx/src/docfx.website.themes/common/common.js

    Line 86 in a977d26

    url += '/new?filename=' + getHtmlId(uid) + '.md';

  15. airbreather commented on Mar 20, 2019

    @airbreather
    airbreather
    on Mar 20, 2019
    Author

    I also feel it like a GitHub bug.

    Yeah. I just played around with it a little bit more, and if I click cancel and then use the Back button on my browser (Firefox 65), GitHub starts ignoring that part of the filename=, which causes me to start editing doc/TheFilename.md instead of doc/overwrite/TheFilename.md like I was before.

  16. airbreather commented on Mar 20, 2019

    @airbreather
    airbreather
    on Mar 20, 2019
    Author

    GitHub bug

    I've opened isaacs/github#1527, and I'll be e-mailing GitHub support with a link to this issue shortly. Follow that issue for any updates on that side of things.

  17. superyyrrzz
    added
    enhancement
    templateThe stock site template
    on Mar 21, 2019
  18. superyyrrzz
    unassigned
    herohua
    on Mar 21, 2019

  19. airbreather commented on Oct 2, 2020

    @airbreather
    airbreather
    on Oct 2, 2020
    Author

    Not sure when this was updated, but the "Cancel" button now returns me back to the repository's home page, which I think is good enough.

  20. airbreather
    closed this as completedon Oct 2, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    templateThe stock site template

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions