Docs/copy edit 1 #315
Docs/copy edit 1 #315
Conversation
kmurphypolygon
commented
Sep 10, 2024
kmurphypolygon
commented
- This PR does a quick scan and update for style guide.
- Please note only one # (H1) per page.
- Also added back the requirements.txt and run script for easy spin up of docs.
- Fixed a link.
wip: alpha release
release: prepare for 0.0.6 release
requirements.txt
Outdated
There was a problem hiding this comment.
Quick comment: we usually put this file as well as run.sh into scripts directory and name them serve-doc-site.sh and docs_requirements.txt (e.g., see here).
There was a problem hiding this comment.
Hi there, I noticed you didn't have them in this repo, so I just dropped in what we normally use in the KL repo and others without rewriting anything. Ideally, we should have a common process across all doc sites so as not to confuse tech writers but feel free to customize this as you wish and if you do customize please add some instructions on how you prefer to spin up the site :)
There was a problem hiding this comment.
FYI: These files are already present in the docs directory, and the docs can built/run using cargo make book or cargo make serve-book depending on whether you want to run it live or not.
EDIT: You can also use docs/mkdocs build or docs/mkdocs serve directly, cargo make just wraps that script in our build system
There was a problem hiding this comment.
ok, cool ... that's great, please go ahead and remove the files I dropped in, no problem
There was a problem hiding this comment.
LGTM! However, I'd like to remove the run.sh and requirements.txt in favor of the ones that already exist in the repo under the docs directory before merging. I can make that change, as well as make sure our docs/README.txt explains how to build and run the documentation using either of the two methods I mentioned in my other comment - unless you'd prefer to do so, just let me know!
| @@ -124,7 +123,7 @@ will be expanding the SDK rapidly over the next few weeks and months, but for th | |||
| you encounter a missing API that you need, let us know, so we can ensure it is prioritized above | |||
| APIs which are lesser used. | |||
|
|
|||
| ### Rust/Miden FFI (Foreign Function Interface) and Interop | |||
| ### Rust/Miden FFI (foreign function interface) and interop | |||
There was a problem hiding this comment.
Shouldn't "foreign function interface" remain capitalized here, to emphasize the correlation to the initials of the "FFI" acronym?
There was a problem hiding this comment.
| @@ -3,3 +3,15 @@ bin/midenc | |||
| bin/litcheck | |||
| .crates.toml | |||
| .crates2.json | |||
|
|
|||
| # Docs platform ignores | |||
There was a problem hiding this comment.
Note: Our docs build in the target directory, which is already ignored, and our docs directory has a dedicated .gitignore for things within that directory, so most of these directives will never be matched.
That said, I'm fine with adding these here anyway (mostly the IDE-specific directives, since we should have those anyway), just in case someone accidentally builds the docs in the project root locally - but just wanted to clarify where you can expect these things to actually be output in this repo.
There was a problem hiding this comment.
Yes, whenever I spin it up locally and make changes, I'm prompted to push a whole load of unnecessary stuff ... so that's why I added these like we have in the Miden base repo.
|
Just a quick note please @bitwalker .. we have an error on main docs This file will remain live and searchable even if there is no menu link to it ... so I'm not sure it that's what you need? Or perhaps you need to add a menu link? |
|
@kmurphypolygon I've added the missing nav item for that page, build instructions for the docs, and the tweaks I suggested, in the latest commit. I'm going to go ahead and merge this, but if you spot any other issues or have other suggested changes, let me know! |
