search

qupath / qupath-docs

QuPath documentation
http://qupath.readthedocs.io/
17 stars 22 forks source link

Add a section about building and modifying the read-the-docs documentation locally? #54

Closed zindy closed 7 months ago

zindy commented 1 year ago

I'm not very well versed in building Sphinx and read-the-docs documentation, and struggled a bit with creating a local environment.

I ended up using the make script make html and pip install all the missing modules, then sphinx-serve.

Edit: The package sphinx-autobuild suggested by Pete below is much better than the one I suggested and is being actively maintenained. It will automatically reload the page in a browser when changes the source file is saved.

I could start a pull request and describe how I got my environment to work, if you'd like?

petebankhead commented 1 year ago

Sounds good - but as with https://github.com/qupath/qupath-docs/issues/53 could you post it on image.sc if you've time?

It would be great to have this documented, but I'm not sure if the readthedocs for QuPath is the right place or not. It might be, but I'm hesitant because everything there is a potential maintenance/update task in the future, it's not really connected to using QuPath, and if many people would submit PRs for doc changes then I don't love the thought of having to review them :)

kaczmarj commented 1 year ago

not sure if this issue is still relevant as it has been almost a year, but today i modified the docs locally and previewed the changes. here is how i did it:

  1. clone this repo and cd into it
  2. install python dependencies. i used venv from the standard library. 
    python -m venv venv
source ./venv/bin/activate
python -m pip install -r requirements.txt
  3. make changes to markdown files in the docs directory.
  4. run make html from the root directory of this project (same directory that contains the README).
  5. run an http server to be able to see the site in a browser. i used python -m http.server --dir _build/html/ & from the root directory of the project. The ampersand & at the end runs the process in the background (on linux and macos), so i can use the terminal to run make html again.
  6. open a browser to the url shown in the terminal
  7. make changes again...
  8. run make html (no need to restart the http server)
  9. reload the browser page to see the changes

i am not suggesting this should be documented in this repo. however, i saw this issue and figured i would add my 2 cents (5 cents with inflation perhaps).

alanocallaghan commented 1 year ago

I'd suggest the README would be the best place to house this info, or a contributing doc

petebankhead commented 1 year ago

After make html you should just be able to open _build/html/index.html - there isn't really a need to run an http server. That's all I use most of the time.

Although if you use sphinx-autobuild you can get some of those advantages, without needing to run make html.

zindy commented 1 year ago

Yes, I second the use of sphinx-autobuild, it automatically reloads the pages when they are changed, it's very good.