bitcoin-dot-org / developer.bitcoin.org Goto Github PK

The footer should be updated so that it is exactly the same as bitcoin.org (including links):

instead of:

Cc: @alexcherman

@cornelius Want to transfer this repository to the organization we are both part of?

https://github.com/bitcoin-documentation

Screenshot:

Not seeing where the word 'documentation' is getting added to the parent breadcrumb, during a cursory search.

Ideas:

• bitcoindocumentation.com
• bitcoindev.info (or .org, .io)
• bitcoindocs.io
• btcdeveloper.io
• btcdevdocs.com
• bitcoindevdocs.com
• bitcoindeveloperdocs.com

Set up docs for localization with Transifex.

Set up documentation to accommodate different versions of Core.

Run make html to reproduce:

/usr/local/lib/python3.7/site-packages/themes/sphinxbootstrap4theme/layout.html:20: RemovedInSphinx30Warning: To modify script_files in the theme is deprecated. Please insert a <script> tag directly in your theme instead.

We should add a button after the Acknowledgements section on the homepage, to lead the reader to the developer guides, so that it's not necessary to scroll back up on the page.

Cc: @alexcherman

Example: https://cornelius.github.io/bitcoin-dev-docs/devguide/block_chain.html#introduction

Following any of the links in the 'Introduction' paragraph results in a 404.

We should use an SVG logo instead of a PNG to improve quality and responsiveness across devices:

...and where the current content can content go.

@cornelius Maybe already done since this is at https://bitcoin-dev-docs.readthedocs.io/en/latest/index.html

...but putting this stub here as a reminder just in case there is anything else related to it that needs to be done.

"Bitcoin for Developers" should appear in the top-left:

Example: https://bitcoindeveloper.netlify.com/devguide/block_chain.html

To reproduce, try to use the search feature.

Result (search page that gets stuck 'Searching', with no results for query):

Note, could be related to the following warning when building (#12):

writing additional pages... search/usr/local/lib/python3.7/site-packages/themes/sphinxbootstrap4theme/search.html:20: RemovedInSphinx30Warning: To modify script_files in the theme is deprecated. Please insert a <script> tag directly in your theme instead.
  {% trans %}From here you can search these documents. Enter your search

We need to ensure that the website displays/functions properly across commonly used devices (iPhone, Android phones, Chrome, Edge, Firefox, Windows, Mac, Linux, etc.).

....but ensure it remains in the sidebar:

We should add page anchor links to the Glossary, so that individual entries / definitions can be linked to and shared.

Run make html to reproduce:

search/usr/local/lib/python3.7/site-packages/themes/sphinxbootstrap4theme/search.html:20: RemovedInSphinx30Warning: To modify script_files in the theme is deprecated. Please insert a <script> tag directly in your theme instead.
  {% trans %}From here you can search these documents. Enter your search

To ensure pages that are shared on social media or in other web apps, display rich media properly.

There is a table at the end of the "initial block download" section which isn't properly rendered as a table.

There is a "edit this page on GitHub" link at the bottom of the left side of each page, which doesn't lead to GitHub, but to the text sources of the page. It should go to the GitHub page where the content can be edited.

On some pages there is a weird effect when scrolling down to the bottom of the page. It can be seen on https://bitcoindeveloper.netlify.com/reference/block_chain.html, for example. The bottom of the left sidebar starts to disappear when the end of the page is reached.

reference/p2p_networking.html links to the GitHub issues of the docs repository in the "Protocol versions" section. This needs to be adapted to link to the bitcoin-dev-docs repo (when we have detached from the automatic import of the original docs).

iPhone 5:

iPhone X:

cc: @alexcherman

The search box is already present in the top navbar on subpages. We should remove it from the sidebar so that it isn't displayed twice:

Cc: @alexcherman

Due to the conversion of the docs from Markdown to RST, most links were created with embedded URLs, e.g.

`text <url>`__

This causes some duplication and makes the RST sources a bit less readable compared to using explicit link references and targets, e.g.:

text_

.. _text: url

It would be better to convert the links to use the explicit references and targets. This probably can best be done by processing the RST sources with a script and generating the necessary changes.

On some pages, the QR code in the footer of the site isn't showing.

Example:

Page: https://bitcoindeveloper.netlify.com/examples/intro.html

Cc: @alexcherman

We can change the text from this:

to this:

Cc: @alexcherman

When viewing subpages (example), if a user mouses over a heading, a page anchor link will appear. This enables visitors to link to and share specific sections of the page they're looking at. We should further improve the style of how that anchor appears, alongside the styling of the rest of the site:

It appears that there may be some formatting issues, and/or missing definitions in the glossary:
https://bitcoindeveloper.netlify.com/glossary.html

Cc: @cornelius

Show:

Do Not Show (highlighted subsections):

Maybe replace the "Show Source" link in the sidebar:

...with an "Edit on GitHub" link.

So that the site looks nice when it gets shared on social networks.

The terms page needs to be merged into the glossary page.

Sphinx supports references across files using its label mechanism. This requires labels to be set at the locations in the documentation which serve as target for references. This will be done after the automatic import has been completed.

Currently an intermediate file holds the labels for the references. These will have to be manually moved to the proper places in the documentation. Then the file can be removed.

Inspiration: http://flask.pocoo.org/docs/1.0/#

The logo is overflowing the hamburger menu on iPhone 5. We need to add a media query to reduce the size:

Cc: @alexcherman

Ran: make html

examples/transactions.rst:809: WARNING: Could not lex literal_block as "json". 
Highlighting skipped.

We should consider adding all BIPs to the site, for easy reference and additional content to associate in-context with other material that's already on the site. It would also be helpful to the user since it would integrate with the site search feature.

There is a table in the serialized blocks section (https://bitcoindeveloper.netlify.com/reference/block_chain.html#serialized-blocks) which is not rendered as table but as text.

Cc: @alexcherman

I think it would be good to have a thorough documentation and guide on Script somewhere on the developer documentation as its own separate category.

Explaining Script would be pretty trivial, as the language itself is pretty simple. But I think we could make things even better by having some sort of interactive "Bitcoin Script playground", with a Script interpreter, and the reader being guided through with simple challenges and examples. There's something about the instant feedback that a playground can provide that would be helpful to a lot of people. I know lots of people use https://www.tryhaskell.org/ to play with Haskell in a similar way.

I'm thinking we can make this more of a process. We can first start writing a decent guide, and then make a design for the playground (how do we blend it into the guide? we obviously want the stack behaviour clearly animated right?), and just go from there. The hardest thing will be the design and UX, because we need to present it right, and make it easy to use. I really believe we should have some challenges, to encourage developers to actually come up with creative ways to use Script to solve actual problems.

Does anyone know of a good bug compatible Script interpreter written in JS? I don't trust the quality of JS projects much, so when I see libraries, I'm generally going to assume there's a ton of subtle bugs. This seems more like the kind of thing where we really don't want any bugs, except to be compatible with existing behavior on the network. I'm hoping someone has a interpreter they can strongly recommend that we can look into.

I could write the guide, but for the other stuff, Web / Javascript development really isn't my strong suit. I wonder if we can find an experienced JS developer with Bitcoin knowledge to help out with this, in exchange for a significant bounty or something. A lot of good can come out of a more interactive approach to educating people about Bitcoin internals.

Reference: https://bitcoin.org/en/bitcoin-for-developers

This needs to be added to the home page.

I'm working on updating the P2P networking reference documentation, so that it reflects the current state and is consistent and accurate. I have some automation for that in place to make it easier to maintain correct format and example information. It's still very much work in progress, so nothing to see yet, but I'll update it once I have something.

I'm putting it down into this issue as one of the things I think should be done before we detach from the import of the original markdown information.

This is to enable more SEO-friendly URLs.