eosnetworkfoundation/docsgen

Scripts for creating docs.eosnetwork.com pulls from various eos nf repos and builds static HTML to power website

docsgen's Issues

Change Welcome to Docs

Rename welcome to docs. Two parts to this request

• Update generate documents and and config for name change
• Update github repository.

Suppress Old Release Notes

only github artifact release notes should show up, release notes stored with markdown should be removed

Update docs site to HTTPS

New AWS load balancer and SSL layer

Document Updates to Style and Presentation

how to update documentation and style

Testing Framework

Seems like we need a crawler.

Objectives

Write a crawler of devdocs portal to perform analysis per URL. Will not summarize analysis across URLs, will not dedup content across URLS

Initial Objectives

• Broken Link checks (single page app all JS)
• check content for each repo
• harness should make testing to prevent regressions

Technology

use cypress , headless browser works everywhere

YAML metadata leaking into content

YAML Leaks into page

Title meta-data at top and it pushes down previous meta-data.

Investigate

The replacement of text might not work when there is more then just content-title.

Example

01_nodeos/05_rpc_apis/index.md

---
title: Rpc Apis
---
---
content_title: RPC APIs
link_text: RPC APIs
---

version redoc6s plugins

the nodoes plugins from openAPI. Need versions for those. config driven at this point.

Test Each Repo is Rendered

Check for H1 tags in key repositories
Check to make sure code references exist for CDT and System Contracts

Acronyms should all caps in title

API RPC and other acronyms should be capitalized.
Example : https://docs.eosnetwork.com/leap/latest/nodeos/rpc_apis/

Links to functions in reference documentation need to be fixed urls

this is how a link to the function modify() in the mandel.cdt reference documentation gets generated:
http://localhost:8080/mandel-cdt/group__multiindex.html#ga4b3556ef69c7faa917f185ae33a34442

the anchor seems to be a GUID which will be different each time the doc gets generated
we need these anchors to be fixed so we can use them in docs and link to functions reference documentation.

Later edit:
the GUIDs are generated the same way (fixed) all the time but we could improve

1. the double underscores could be simplified
2. instead of GUIDs have integers?... or a human readable anchor

Fix Title and Nav for Resource Directory

in CDT and EOS System Contract the doxygen/doxybook2 files fall into a resource directory fix by doing the following

• Prefix with number 90_ to drop to bottom of index
• Capitalize Title
• Make a proper index if needed

Add Release Notes to documentation

add release notes for leap.

Name Change Welcome repo to Docs

Code Reference Empty for CDT and EOS-System-Contracts

Found doxybook2 executable missing.

Folders without index files are displayed

They should display 404 not found or similar for security reasons.

e.g. https://docs.eosnetwork.com/leap-plugins/latest/

Tracking & Privacy Requirments

Starting an issue so we don't forget this work item. Need to know how to implement tracking, marketing tags, and any special features to support EU/CA privacy requirements.

Duplicate titles in sidebar

Sometimes markdown file can have the same name

1. eosjs module directory and eosjs module markdown file.
2. system-contracts has two about system contracts

AWS permissions for automated bot

need roles, groups, and devdoc user to automatically build documentation on each release.

Regenerate OpenAPI for nodeos

updates to get_info new endpoints send_transaction2, trace and compute

UI/UX design changes for first release

expect work coming in this direction

Always Working Reference Links

Example:
/action-reference/eosio.bios -> /reference/mandel-contracts/classeosiobios_1_1bios.html

Put this mapping in one location, may need to correctly handle release or API versions

Update Crawler to use sitemap

NOTE alternative is to use algoria crawler.

Edit crawler/getLinks.js to crawl https://docs.eosnetwork.com/sitemap.xml

Mostly likely want to crawl in groups by first level directory. For example param of group=cdt would crawl

• /zh/cdt
• /ko/cdt
• /cd

Filter out all /blog do not crawl those
Mostly likely want to crawl latest stable release, so you may need a version param as well.

Having our own crawler is faster and cheaper, but fragile.

Add Mermaid support for graphs

Feature request now that mermaid is an official part of github
facebook/docusaurus#1258

Make Homepage Reasonable Entry Point

Put 5 tiles on homepage

• How EOS Works
• Getting Started
• The EOS Stack
• API References
• Resources

Display Versions for Documentation

Ability to show versions of documentation to match releases from repos

Align system contracts EULA with ENF principles and goals

Big EULA here, do we want this? How should this show up in dev doc portal?

https://github.com/eosnetworkfoundation/eos-system-contracts/blob/main/contracts/eosio.system/ricardian/eosio.system.clauses.md
eosio.system.clauses

Staging URL for new content

setup /preview path for staged content. Setup /latest for current release and stable version.
PR #52

Add Tags for GitHub Origin

Add front matter YAML to documents at build time. Include

• github repo
• path to file on github
• github branch or tag

Capitalize Titles

Shell Linter on for commits

Should run for install_ scripts as well

Documentation staging site

The DevRel team needs a new hostname like docs-staging or similar on the eosnetwork.com domain to run the docs build scripts. This is needed so they can inspect the docs and make sure they render correctly prior to publishing on docs.eosnetwork.com.

CDT has Markdown Out in Breadcrumb

http://localhost:3000/cdt/latest/

Daily Staging builds

Requirements

• configurable devdoc branch
• creates update file
• cron for daily 4am ET

404 for some valid reference doc links

go here
http://docs.eosnetwork.com/next/eosdocs/smart-contracts/mandel-cdt/how-to-guides/multi-index/how-to-modify-data-in-a-multi-index-table/

and click the multi-index::modify link
it shows 404
the link is valid (http://docs.eosnetwork.com/next/reference/mandel-cdt/group__multiindex.html#ga4b3556ef69c7faa917f185ae33a34442)
you can open it in a separate tab and it will load fine.

H1 tags link in document navigation

Seems like anchor tags are not generated for heading level 1 (#) in rendered markdown files. This also affects page navigation since first section titles/links are missing. Not sure whether filing this as a bug, enhancement, or neither. Seems like docusaurus is adhering to the unofficial rule that 1st headings are used for page title, while 2nd/3rd+ headings used for actual section titles. If we also adhere to this, then we need to update all docs and convert # —> ##, ## —> ###, etc. Thoughts? @ericpassmore

Run build documents by default

for generate_documents.sh run npm run build by default. Add -x as suppression flag to prevent running build. Suppression of build is needed when running several generation processes back to back. You only want to run on the last build

Remove restrictions on Welcome install

Currently only the following directories (plus the glossary) are copied from the welcome repo when building the document portal. Need to remove these restrictions and copy over all directories.

• 01_overview
• 02_getting-started
• 03_tutorials
• 04_protocol
• 05_community-developer-tools
• 06_eosio-blockchain-networks
• 07_migration-guides resources

Move Search box to Sidebar

Steps

• Swizzle search box
  • This creates js file under your project
  • restart dev server
• edit sidebar.js to include newly swizzled file
• search box should now be in sidebar

Question: how do we remove from NavBar or does the act of swizzling remove it?
Question: does the swizzled search box have DOM structure or just behaviors? Do we need HTML/CSS styling

Swizzling will also allow you to replace search box with other options like algolia if you like

Broken info tag in markdown

Appears to be broken, need to investigate

cleos/how-to-guides/how-to-create-an-account

Support for Info and Warning labels/tags

We need support for these custom markups below:

[[info | Implementation location]]
[[warning | Implementation location]]
[[caution | Implementation location]]
[[danger | Implementation location]]

When they are present in an md file the text should render differently (color and background) for each of them.

Consistant UI/UX for external links

Need to scope work covering the content in references

• open API docs
• swift docs
• java docs
• doxygen docs for C/C++ code
  • mandel
  • mandel-contracts
  • mandel-cdt

Generation of index markdown

investigate best way to automatically create index.md files if they do not exit.

Duplicate Page in CDT Return Values From Actions

Attempting to create page at cdt/latest/features/return_values_from_actions, but a page already exists at this route.

Add Mount s3 bucket to AWS Host

Out of space need to add new s3 bucket to AWS host

Make host configurable for tests

use a configuration file to set the host:port for testing.

Restructure code by repository

Needed to align repo PR and release with documentation update. Going forward github scripts will generate and pull docs on a new release. github scripts work on a repository level so code must align to repos

Get bigger host for builds

Need AWS host with 4GB min 8GB would be good for future proofing.

End to End testing with cypress

https://docs.cypress.io/guides/end-to-end-testing/writing-your-first-end-to-end-test#Write-a-real-test

B1 links and cyclical links

There are links that lead back to the b1 docs: http://docs.eosnetwork.com/next/eosdocs/client-side/jsdocs/

I see these are coming from https://github.com/eosnetworkfoundation/mandel-eosjs

Looks like we need to go through the readmes and make sure there's no links to b1 docs either
Also, the fact that the links are cyclical is strange (readme leading to docs which lead to readme)

Add search to document repo

Consider using https://www.algolia.com/