search

pine64 / bl602-docs

Documentation of the BL602 IC
https://pine64.github.io/bl602-docs/
65 stars 41 forks source link

Build docs from source .rst files #1

Closed Newbytee closed 3 years ago

Newbytee commented 3 years ago

See https://github.com/pine64/bl_iot_sdk/pull/5 for original PR. Note that the zh directory currently just contains the old docs and the en directory contains the self-built docs, not any actual English docs. I leave that for another PR.

Avamander commented 3 years ago

Hm, I don't think it's a good idea to put build output in source folder. Can you place it in /html?

Newbytee commented 3 years ago

Hm, I don't think it's a good idea to put build output in source folder. Can you place it in /html?

Actually, should we keep build output in the repository at all? We could use something like https://readthedocs.org/ to host it.

Newbytee commented 3 years ago

I set the docs' build directory to be /build, so if you build the docs in html format they will be outputted to /build/html. I also added /build to gitignore.

Avamander commented 3 years ago

Actually, should we keep build output in the repository at all? We could use something like https://readthedocs.org/ to host it.

Github Pages can host it just as nicely and it's one less external service provider that has to be dealt with.

I set the docs' build directory to be /build, so if you build the docs in html format they will be outputted to /build/html. I also added /build to gitignore.

Can you change it to just html? There's no need for the build prefix IMHO.

Newbytee commented 3 years ago

Actually, should we keep build output in the repository at all? We could use something like https://readthedocs.org/ to host it.

Github Pages can host it just as nicely and it's one less external service provider that has to be dealt with.

Good point. I hadn't thought of that.

I set the docs' build directory to be /build, so if you build the docs in html format they will be outputted to /build/html. I also added /build to gitignore.

Can you change it to just html? There's no need for the build prefix IMHO.

I'm not sure how I would do this. Currently the build directory is set to /build, but as Sphinx supports generating docs in other formats than HTML it puts the HTML ones in a subdirectory of /build. I could, of course, make it part of the Makefile to move the docs back down into build and delete the subdirectory, but that feels ugly.

Newbytee commented 3 years ago

I gitignore'd build/doctrees and pushed the built docs in build/html

Avamander commented 3 years ago

I'm not sure how I would do this. Currently the build directory is set to /build, but as Sphinx supports generating docs in other formats than HTML it puts the HTML ones in a subdirectory of /build.

Setting build output location to "./" or "" can't be done with Sphinx?

Newbytee commented 3 years ago

I'm not sure how I would do this. Currently the build directory is set to /build, but as Sphinx supports generating docs in other formats than HTML it puts the HTML ones in a subdirectory of /build.

Setting build output location to "./" or "" can't be done with Sphinx?

I somehow didn't think of that. Done, thanks.

gamelaster commented 3 years ago

Hello @Newbytee , @muscache and @username223 , Thank you very much for your pull requests! For receiving the free PineCone, please sign up at this link. (If there will be any issues with signing up, please let me know here).