Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: new light theme and various other updates #209

Merged
merged 13 commits into from
Sep 17, 2019
Merged

Docs: new light theme and various other updates #209

merged 13 commits into from
Sep 17, 2019

Conversation

mosra
Copy link
Collaborator

@mosra mosra commented Sep 12, 2019

Motivation and Context

What's done:

  • The m.css submodule is updated with mostly CSS-related changes in order to allow light themes work better, plus a bundle of changes and fixes done when porting habitat-api python docs to it
  • Cross-linking to the quaternion types as well (originally it was using some broken *.inv file and nothing worked)
  • New light theme using Habitat colors (there's still quite some work left to be done by some designer, you'll see once you start using the more colorful features of m.css)
  • Using Pygments' builtin "pastie" theme for code highlighting to fit better with the light theme (feel free to adapt / change that tho)
  • The Magnum Python Bindings have a stable URL scheme now, which means existing links didn't work anymore. The *.inv file got updated to fix that.
  • The build_docs.sh helper got moved into docs/ and it now also does CSS compilation and has a possibility to use an external m.css project instead of the submodule (I'm using that a lot for iterations)
  • The docs now have a favicon, brand logo and a theme color so e.g. your android browser will match its chrome color with the page; also there's a copyright footer added

How Has This Been Tested

git submodule update --init
cd docs
./build.sh
open ../build/docs/habitat-sim/index

Not sure why I thought they aren't.
For some reason I grabbed a totally broken inventory file at first. This
one is less broken but the names get inspected weird so it needs to be
fixed up after.
Somehow it doesn't generated when it's there. Or something.
The resulting CSS is generated by the build.sh script and added to
.gitignore -- changes should be made to theme.css / pygments-pastie.css
instead.
Similarly to how API does that.
The URL scheme got stabilized there, so all links are different now.
@facebook-github-bot facebook-github-bot added the CLA Signed Do not delete this pull request or issue due to inactivity. label Sep 12, 2019
@erikwijmans
Copy link
Contributor

Request to change Habitat Python Docs to Habitat API Docs. This needs to be both in docs/conf.py and Doxyfile-mcss

@mosra
Copy link
Collaborator Author

mosra commented Sep 13, 2019

Done in 810e303, thanks. Also did a minor change on the API side (facebookresearch/habitat-lab@e66bfa8), felt more consistent that way.

So it's "relocatable", i.e. when running the whole site on localhost,
the navbar links goes to the main site instead of out into the wild.
mathfac pushed a commit to facebookresearch/habitat-lab that referenced this pull request Sep 16, 2019
A counterpart to facebookresearch/habitat-sim#209. What this does:

*  Rewrites everything that was in Markdown before to a reStructuredText (four tutorial files)

*  Rewrites docstrings to use the m.css Sphinx-like syntax
*  I took the externally-referenced images and put them directly in the repo because I think it's easier to ensure it stays in sync that way (and those aren't too big). If that's a problem, I can revert that change.
*  Otherwise, everything kinda the same as on the Sim side.
Most importantly, this references a lot of files from the habitat-sim repository and also puts the output there. This is done mainly in order to keep the style and symbol crosslinking in sync and also so you have C++ Sim, Python Sim and API docs next to each other, with them being easily switchable from the top navbar.

- `New Actions <std:doc:new-actions>`
- `Notebooks <std:doc:notebooks>`
- `Creating a stereo agent <std:doc:stereo-agent>`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be links yet?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you mean the TODO, no, that still holds ... i had to prioritize to not spend next 16 years on the generator :)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, no problem, just wanted to make sure there wasn't something I was missing :)

@mosra mosra merged commit 4335113 into master Sep 17, 2019
@mosra mosra deleted the docs2 branch September 17, 2019 18:15
eundersander pushed a commit to eundersander/habitat-sim that referenced this pull request Aug 6, 2020
Lists are also objects and [[]] * 5 just creates a list of 5 pointers to the same thing.
Ram81 pushed a commit to Ram81/habitat-web-sim that referenced this pull request Dec 10, 2020
* docs: dang, I forgot to clean this up.

* docs: relative paths actually *do* work.

Not sure why I thought they aren't.

* Cross-link to the quaternion package as well.

For some reason I grabbed a totally broken inventory file at first. This
one is less broken but the names get inspected weird so it needs to be
fixed up after.

* Move the build_docs.sh helper into the docs directory.

* Updated m.css submodule.

* docs: capitalize project name.

* docs: move the generated tagfile outside of the doxygen output dir.

Somehow it doesn't generated when it's there. Or something.

* docs: make it possible to supply external m.css.

* docs: switch to a custom light theme.

The resulting CSS is generated by the build.sh script and added to
.gitignore -- changes should be made to theme.css / pygments-pastie.css
instead.

* docs: link to tutorials from the main page.

Similarly to how API does that.

* docs: update magnum bindings doc inventory.

The URL scheme got stabilized there, so all links are different now.

* docs: less confusing names in the navbar.

* docs: make main project URL just a /.

So it's "relocatable", i.e. when running the whole site on localhost,
the navbar links goes to the main site instead of out into the wild.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CLA Signed Do not delete this pull request or issue due to inactivity.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants