steemit / devportal Goto Github PK

I don't know if this is covered in any of the other planned issues, but it would be good to have info on how to add "Pay with STEEM" options to a website

Reference:
https://steemit.com/steemdev/@adept/how-we-added-pay-with-steem-sbd-options-to-the-thesteemitshop-shopify-store-using-steem-connect

Production environment has bad resource and left nav urls, even though they work in dev.

AC

• nav works in prod
• js, css, images load in prod

Original Story:

@Kennybll recently created this blog post which would probably be a good addition to the dev portal:

https://steemit.com/steem/@kennybll/steem-code-deep-dive-config

Re-storied by @inertia186:

As an API client developer, I would like to know what all of the results of get_config means, so that I can utilize them to generalize my client.

Many of these values would be handy for API clients. If an API client accepts a URL to a node, one of the first things the client can do is interogate the node with get_config to find out basic things like address prefix, symbols (WIP), and type of blockchain (testnet/maintet).

The original story talked about a deep dive into the config header. But all of those values are hard to find for non-c++ developers. And they're all present in the get_config results, e.g.:

curl -s --data '{"jsonrpc":"2.0", "method":"condenser_api.get_config", "params":[], "id":1}' https://api.steemit.com | jq

Not only that, but they're properly named in the method results with STEEM_ as the prefix instead of STEEMIT_.

AC

• Create a new recipe in the style of "Understanding Dynamic Global Properties"
• Link to this new recipe from API definitions for get_config.

Need a section that lists any possible third-party tools that might have popped up like a steemdb or steemd versions pointing at a testnet, list them in a table.

AC

• each testnet gets its own testnet_id (use the first seven characters of the chain id)
• links to these front-ends live in the .yml
• add a document iterates and presents the .yml as its own page

Use neat_json on API Definitions.

AC

• switch from jsonify to neat_json
• verify maximum column length

Tutorials derived from output of #40
A snippet from the raison de être parts of each tutorial, with and explanation.
This content should probably be cloned from a .md file in the tutorial itself.

AC

• A well defined story for each tutorial defined in #40 has been created within the devportal repo and added to the backlock
• Each story's name starts with JS-T:

Document all Appbase API methods.

A quickref was created - though this should not be considered authoritative, all methods described should be validated for correctness: https://steemit.com/appbase/@holger80/api-methods-list-for-appbase

AC

• Set of yml files, one for each method prefix (eg database_api, block_api)
• Contents of each yml file 1: describes the context and purpose of the resources at that prefix
• Contents of each yml file 2: a prefix specific list of (api method, parameter json, expected response json, purpose)
• Contents of each yml file 3: each item in the prefix-specific list should be hash-linkable (suggest using <api prefix>.<api method>
• Create page for Appbase API Definitions (AAP)
• AAP: Renders each yml file in a nicely formatted fashion, similar to glossary page.
• AAP: List of common properties of request & response with definitions at the top
• AAP: optional - JSON on the page is prettier formatted, regardless of formatting in YML file.

The memory requirements for steemd nodes is out of date in the below text. The wording is also a little confusing - what is "ca", why end with :

Dockerized p2p Node
To run a p2p node (ca. 2GB of memory is required at the moment):

Dockerized Full Node
to run a node with all the data (e.g. for supporting a content website) that uses ca. 14GB of memory and growing:

The build process for the site should pull in the python documentation from the steem-python repo, and process it into whatever format it needs to be in for display inline on the devportal.

We want to have a clear set of expectations when writing Javascript tutorials for developers. We want to define how good they must be, so that we don't over-explain. We want to define what tools they have available if they're writing a Node.js app, and what tools if they're writing a Client-side only app.
If they're writing an app using both client & server side code, the tools should be a union of the Client/Server sets.

Notes and debate can/should be taken on this issue.
Use current best practice.
No minimum use of 3rd party codebases, NO heavy UI frameworks, except vanillaJS which is permitted (see http://vanilla-js.com/)

AC

• Define the minimum skillset we expect a Javascript developer to have
• Define the Javascript Development environment we expect for Server side development.
• Define the Javascript Development environment we expect for Client side development.
• The above are defined in a single comment on this issue. And be labeled Conclusion

We need a consistent pattern for all developer portal tutorials so users know how to orient themselves when entering a new tutorial.

• establish a structure for the text portion of all tutorials
• establish conventions for the 'new code complexity' of tutorials
• describe the above in a comment on this issue with the title Results

The testnet is up. Evaluate the resources contained in https://github.com/steemit/steempunks/issues/274 and create a set of stories for putting testnet documentation into the developer portal.

Notes
Guidelines for stories. General testnet documentation should be language agnostic where possible.

AC

• list of stories in a comment labeled Results with acceptance criteria as sub-bullets
• each story created, and references this story, and the above 274 in its description

Use branch 231-tutorials for commits
Links to devportal-tutorials-js

AC

• links to devportal-tutorials-js AND to specific tutorial
• tutorial follows code from example in devportal-tutorials-js

AC

• the text should read Steem not **Steem**.

See here: https://github.com/xeroc/python-steem/blob/master/README.md

When performing a search in devportal, we land on a page full of broken assets and no results.

It is possible for developers to write an application that connects to a locally run Vessel instance to submit transactions that require signing with keys. This would be good to include documentation for.

as a developer, i found it hard to figure out which methods do what -- currently the descriptions are like "Get Discussions By Author Before Date" -> getDiscussionsByAuthorBeforeDate -- not very helpful ;)

also it'd be useful to have types & descriptions for method arguments.

The Javascript section of the main page on the developer portal is confusing and not up to current standards, it needs to be moved to its own page, and de-emphasized.

AC

• the steem-js focused tutorial needs to be moved to its own page.
• the "JAVASCRIPT" portion of the main nav is removed
• a link to the legacy documentation is created in or near the Javascript section of the tutorials page
• text around the link says something like the below

Our tutorials use currently use dsteem, which is significantly faster on the client, is better documented, and has a strong path forward. If you prefer to use `steem-js` you can find our legacy getting started section [here](url to location)

Since we don't have any python tutorials yet, we need to remove that link.

AC

• python link is no longer present in nav

So from the documentation, it seems we have to make an HTML file and call a JS file to query that HTML page and send post data that way. This is incredibly strange to me. Is this kind of practice common? Why not just use standard JSON calls and endpoints like every other API? Does the fact that the API is based on blockchain make this difficult?

To familiarize myself with the tutorials writing process, I've added some initial ruby tutorials.

AC

• Sync up current ruby tutorials branch so that it matches existing tutorials JS, where applicable.
• Add steps to clone the repo to access related ruby tutorial .rb files.

Use branch 231-tutorials for commits
Links to devportal-tutorials-js

AC

• links to devportal-tutorials-js AND to specific tutorial
• tutorial follows code from example in devportal-tutorials-js

Steemit has a new Developer Advocate. The community should be able to contact hrm.

All API docs should be autogenerated, we can use a tool like sphinx for the python code to generate documentation from docstrings automatically and then convert it to markdown using pandoc or similar.

I'd be happy to put together a script to do this conversion for the python codebase, i'm not familiar with similar tools for the javascript codebase though.

Longer term we probably want automatic documentation for the JSON-RPC API in steemd too - i'd be amazed if tools don't exist for doing this from a schema.

The Liquid json formatter leaves much to be desired. There doesn't appear to be a "pretty" option.

We want a colorized, well-formatted pretty print option that does not rely on .yml or .md formatting

Notes

• This is a spike (research, with optional execution). Time box yourself to no more than one day.
• Possible resource: https://stackoverflow.com/questions/86653/how-can-i-pretty-format-my-json-output-in-ruby-on-rails
• Jekyll currently uses highlighter rouge. A search for highlighter rouge jekyll may yield information (speculation: could be as simple as css formatting once use with .yml is figured out)

AC

• Discovery or implementation of a pretty print filter or utility that can be used with Jekyll
• Documentation of filter/utility/practice as comment on this story
• Decision about inclusion of above filter/utility in our dev portal
• Optional - at least one use of said filter in our dev portal with .md file
• Optional - at least one use of said filter in our dev portal with .yml file

The appbase api call and response definitions are already in the codebase. Make a menu item for them, and make sure they still work correctly

AC

• main nav item exists for appbase api docs
• api docs work on separate page in reasonable manner.

from Public Nodes, or self build?

• JS -> Getting started points to steem npm package which I think should be replaced with @steemit/steem-js
• JS -> API references extending descriptions of each request, difference between websocket and json-rpc nodes
• JS -> Examples section references snapsteem.com which is broken, it probably needs to be reworked with new examples or tutorials should replace it. Quick Start -> Example could be moved under JS -> Examples too...

@relativityboy

We need to keep the main page 'lite', with details primarily of resources most people are going to use.
The testnet documentation needs to be on its own page.

Consider incorporating the documentation with the page created in #73

AC

• Testnet documentation is on own page at /testnet
• Testnet link still goes to documentation

There have been two new RPC nodes added by members of the community:

@steemgigs added: steemd.steemgigs.org
@ausbitbank added: rpc.steemviz.com

AC

• Python getting started tutorial is on own page, with separate url. Not on main page
• Python getting started tutorial is referenced in it's own section on the tutorials page.
• Python section of the tutorials is referenced in the Tutorials list in main nav (does not have it's own large nav item.

Add contributors section to Devportal to explain best practices and how to contribute tutorials and information to the Devportal.

AC

• Add Contributors section
• Add Contributors nav item to top of navigation
• Add Syntax Highlighter/prettifier guidelines

Document how to create Testnet instance of Steem for advanced users...

AC

• Tutorial should have clear step by step guidance on running Testnet
• Changing parameters
• Server specifics, hosting testnet
• Additional details on how to allow API or getting started with Testnet usage similar to this: #62
  • Description of official testnet

We need to document the condenser api

AC

• all appbase calls related to condenser are documented in the same way the current set of apis are.
• documentation appears on appbase api docs page

We have a few small issues with duplicates in glossary items. One, is an exact duplicate as mentioned by a community member in pull #88. But also, there are less obvious duplicates, so here's all of them:

• steem as "Steem" and "STEEM"
• node straight up duplicate
• transaction as listed in Chain Basics and Transactions sections

As we expand the glossary, we need a strategy for dealing with these kinds of duplicates. Obviously, if it's truly redundant (like node), don't do it.

But The "Steem" vs "STEEM" is warranted. We do make a distinction between them. Unfortunately, the way DOM IDs are created in the document, they both become id="steem" so anchors get messed up.

Then we have logical reasons to list a definition twice, as in transaction. A transaction has a basic meaning as well as a specific meaning in the Glossary.

We could just add parentheticals to items that collide. E.g.:

• Steem
• STEEM (currency)
• Transaction (Basic)
• Transaction

AC

• Should DOM ID be a consideration in the terms?
• If so, should we add parentheticals to duplicate items?
• Roll up conclusion in this issue with the title Result

AC

• put readme for steemit/devportal-tutorials-js#6 into website in same manner as those already present
• menu item on tutorials page just after steemconnect with appropriate description

At https://developers.steem.io/tutorials-javascript/steem_js

There is a link to "snapsteem". The site is defunct. Remove, or remove and replace, the reference.

AC

• Snapsteem link and associated content directly referencing the site or a link to that site is removed/modified appropriately.

There are couple other tools helping developers to sync blockchain to mongodb, might be appropriate in https://developers.steem.io/#community-steemdata

eSync (nodejs): https://github.com/esteemapp/esync
ChainSync (python): https://github.com/aaroncox/chainsync

Write a rake task that will compare what we have in _data/apidefinitions and add anything that's missing. E.g. we should be able to use a command like:

rake scrape:api_defs

... which will check the existing definitions and add new ones.

AC

• missing apis should be added as new .yml files
• default new apis with empty values for description
• missing methods should be added to the corresponding api .yml file - and preserves any existing data. If there are api methods that are no longer present, they're marked as deprecated.
• default new method names with empty values for purpose
• readme in the repo with instructions as to how to use, and expected behavior
• generated yml file includes comment at the top as to how it was generated, and a readme to the instructions.

Since we have restructured the tutorials the previous javascript and python tutorials are now obsolete.

• _javascript tutorials are removed
• _python tutorials are removed

It appears to be controlled by adjust.js. It works as expected on legacy getting started, but I can't get it to work right elsewhere.

Steps to recreate:

Add a section to the right_code header item, e.g.:

    <p class="right-section-title">Example</p>
    ```javascript
    const { Client } = require('dsteem');
    ```

Add a section to the main part of the document, e.g.:

    ### Example

    Here is my example paragraph.

See if the left and right sections automatically adjust so that the code example is next to the paragraph about it.

It also appears that the left header cannot contain spaces, even though the right header does (it automatically replaces spaces in the id with dash).

AC

• left and right paragraph headers match positions
• spaces are allowed in the header names

AC:

• A list of tutorials and website appropriate descriptions in comments below.
• Tutorials should be listed in order of difficulty.
• A full set of tutorials will at a minimum replicate the api-call functionality of steemit.com.
• One rollup comment labeled Results with a list of all the tutorial names. - This list is in "suggested order"

API Definitions do not need the "right_code" section, so it should be dropped.

AC

• page uses full width
• each sub document needs to use row instead of doc-content.left-docs

https://github.com/steemit/devportal/edit/master/_python/getting_started.md

 Install with python-steem:

$ sudo apt-get install libffi-dev libssl-dev python-dev
$ python-steem3 install steem

I think this should be

Install with pip:

$ sudo apt-get install libffi-dev libssl-dev python-dev python3-pip
$ pip3 install steem

steemit/devportal-tutorials-js#7

We currently have jekyll-rouge up and running in our codebase. It's good for highlighting, but it doesn't guarantee consistent indentation and code formatting. We need to include a library that does that a-la prettier

AC

• determine library - add as comment titled Results
• describe mechanism of prettification (server side, browser side, commit hook?) - add to Results comment.
• implement mechanism
• update content code/json snippets as needed

The Javascript tutorials page should outline the dev environment, and base set of skills a developer need to have to get the most out of the tutorials.

Notes

• Use #36 & #39 as source material
• If the description gets too wordy, may be moved to a separate page titled "Environment and Skills"

AC

• A paragraph or 3 nicely summarizing the environment, tools, and skills a developer needs to have.
• Should be brief. Names of tools and environments are linked to educational, or main, resources for those items.
• Should be smooth english writing, preference for no bullet points.
• Whether a separate page, or on Javascript tutorials page, should be hash linkable.

Our tutorials need to level set expectations for the developer's environment. We could call it "application environment guidelines" or some such. It should go at the top of the tutorials section, and be hash linkable.

Use results from #39

AC

• Describe base skill level expected of a developer. (Links to resources for acquiring those skills)
• Establish a base environment that will work in node 8+ and supports the newest version of ES. Observations and final environment description should be in comments on this issue.
• Add English language description of the environment (Environment Description), include links to appropriate 3rd party resources & tutorials so a JS developer with little experience can bootstrap themselves.
• Environment Description should be deep linkable.
• Environment Description should be at the top of the tutorials section after the greeting and/or on the intro page of the tutorials section if the section has multiple pages.