Create .readthedocs.yaml #94

ryandanehy · 2023-11-29T22:28:27Z

Post ReSolve documentation at readthedocs.

Include Doxygen generated source code documentation, as well, and provide a link to it on readthedocs..

docs/conf.py

ryandanehy · 2023-12-01T21:30:08Z

Problem with doxygen generated html resolved. Had to use the post_build command found in the readthedoc.yaml as stated in read the docs docs

Here is the link
https://resolve.readthedocs.io/en/latest/

pelesh · 2023-12-01T21:42:22Z

Problem with doxygen generated html resolved. Had to use the post_build command found in the readthedoc.yaml as stated in read the docs docs

Here is the link https://resolve.readthedocs.io/en/latest/

Fantastic!

ryandanehy · 2023-12-01T21:53:08Z

Problem with doxygen generated html resolved. Had to use the post_build command found in the readthedoc.yaml as stated in read the docs docs
Here is the link https://resolve.readthedocs.io/en/latest/

Fantastic!

In this branch should I remove the github based hosting docs or keep that for now too? Long story short after this is merged we will have two different places for this our docs which seems unnecessary.

pelesh · 2023-12-01T22:10:02Z

In this branch should I remove the github based hosting docs or keep that for now too? Long story short after this is merged we will have two different places for this our docs which seems unnecessary.

I would remove github-hosted docs in a separate PR. I think a little bit of redundancy is good at this time. By the way, should we merge #92 first and then this PR? @cameronrutherford, please chime in, as well.

pelesh · 2023-12-01T22:13:24Z

CC @kswirydo

pelesh

Looks good, I added some minor suggestion.

pelesh · 2023-12-01T22:41:51Z

docs/conf.py

+with open('./doxygen/Doxyfile.in', 'a') as f:
+    f.write("\nOUTPUT_DIRECTORY=../_readthedocs/html/doxygen")


It would be super helpful to document where this directory is locally and where it is copied to later.

This directory does not exist locally and will only exist on the read the docs server where the builds happen.

I think adding a comment like this would be helpful. It beats me why it is ../_readthedocs. It is ../ relative to where? In any case, we can create a separate issue to document these pathing issues, no need to hold this PR.

pelesh · 2023-12-01T22:44:57Z

docs/conf.py

+html_static_path = [os.path.join(conf_directory, 'sphinx/_build/_static')]
+


Same here, it would be helpful to understand why this specific path is chosen. Thinking of me trying to figure out why docs are not showing up at the remote location a few months from now :).

pelesh · 2023-12-01T22:46:48Z

docs/doxygen/Doxyfile.in

-OUTPUT_DIRECTORY       = sphinx/_build/doxygen
+# OUTPUT_DIRECTORY       = @PROJECT_BINARY_DIR@/html/doxygen



Are we using Doxygen default output dir?

This is replaced by the command in conf.py but I will document this.

docs/index.rst

pelesh

This looks good to me. There are only some minor issues, mainly documenting scripts, that need to be handled.

I would wait for @cameronrutherford's feedback before merging this, but as far as I am concerned this is good to go.

cameronrutherford

A few necessary changes, but this is awesome!

I still think this is the bigger selling point over quarto (having versioning), but I would pay big money to figure out how to mix the two... I think it's possible

cameronrutherford · 2023-12-02T18:48:58Z

.readthedocs.yaml

+  apt_packages:
+    - ghostscript
+    - graphviz
+    - texlive-full


I don't know if you need texlive if we aren't rendering into a PDF.

I don't know what ghostscript is either...

Ghostscript is a tool that processes postscript files and is often used with tex engines. I think it may be needed if we want to produce docs for printing. If it is not causing any unnecessary overhead, I would leave it as is for now.

cameronrutherford · 2023-12-02T18:49:08Z

.readthedocs.yaml

+    post_build:
+    - cd docs && doxygen ./doxygen/Doxyfile.in 


Just what we were looking for :)

cameronrutherford · 2023-12-02T18:50:39Z

docs/index.rst

 User guides and source code documentation are always linked on this site.
 `ReSolve Github Project <https://github.com/ORNL/ReSolve>`_.
-`Source documentation <doxygen/html/index.html>`_
+`Source documentation <html/index.html>`_


Since this page is a super quick redirect, maybe we could just make the sidebar entry link straight to Doxygen docs? IMO we could also change name to just Doxygen Docs then as well. (maybe Source Documentation is cleaner language)

I suggest we leave links to both, general ReSolve documentation (top level docs) and the direct link to source documentation (Doxygen generated). The former is for users who just want to interface to ReSolve and the latter is for contributors who need to know about ReSolve's internals.

@cameronrutherford looks like sphinx toctree can only include rst based documents in the toctree and there isn't very obvious support for including html files in the toctree which is what the doxygen page are.

cameronrutherford · 2023-12-02T18:52:05Z

docs/sphinx/notice.rst

+Notice
+*******
+
+.. mdinclude:: ../../NOTICE


https://resolve.readthedocs.io/en/latest/sphinx/notice.html - you can't simply use an extension without installing it ;)

See #92 and look a little closer into what python deps I install

So why don't we simply write these files (license and notice) in rst format and include them without the conversion tool?

ryandanehy and others added 12 commits November 29, 2023 14:27

Create .readthedocs.yaml

7c5fe3f

Update .readthedocs.yaml

7192b53

Update conf.py

c2bb3f4

Update conf.py

1baaff1

Update Doxyfile.in

f1a85e4

Update Doxyfile.in

b981ac4

Update conf.py

8479e2a

fixing stuff

6f5b146

Update index.rst

48133ad

pathing test

cde9ff0

pathing test

5a6f3ff

pathing test

caac39d

cameronrutherford reviewed Dec 1, 2023

View reviewed changes

docs/conf.py Outdated Show resolved Hide resolved

[email protected] added 9 commits December 1, 2023 11:08

adding post_install

bbae030

fixing post_install

d2cf38d

fixing post_install

7b4dce4

fixing post_install

213111d

adding link checker

db512fb

food

a84593c

comment out links [skip ci]

3857eef

replace pre_build with post_build [skip ci]

b31bb0a

replace pre_build with post_build [skip ci]

379eedb

ryandanehy marked this pull request as ready for review December 1, 2023 21:28

pelesh added this to the First Release milestone Dec 1, 2023

pelesh reviewed Dec 1, 2023

View reviewed changes

pelesh approved these changes Dec 2, 2023

View reviewed changes

cameronrutherford requested changes Dec 2, 2023

View reviewed changes

[email protected] added 4 commits December 4, 2023 09:27

Add documentation and slight changes

f2b1969

Add documentation and slight changes

bc27708

test

2a7cd39

test [skip ci]

b3875e2

ryandanehy requested a review from cameronrutherford December 4, 2023 18:17

pelesh merged commit 2d2b21a into develop Dec 4, 2023

pelesh deleted the readthedocs branch December 11, 2023 16:57

pelesh assigned ryandanehy Sep 20, 2024

pelesh added documentation Improvements or additions to documentation enhancement New feature or request labels Sep 20, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Create .readthedocs.yaml #94

Create .readthedocs.yaml #94

ryandanehy commented Nov 29, 2023 •

edited by pelesh

Loading

ryandanehy commented Dec 1, 2023

pelesh commented Dec 1, 2023

ryandanehy commented Dec 1, 2023

pelesh commented Dec 1, 2023

pelesh commented Dec 1, 2023

pelesh left a comment

pelesh Dec 1, 2023

ryandanehy Dec 1, 2023

pelesh Dec 1, 2023

pelesh Dec 1, 2023

pelesh Dec 1, 2023

ryandanehy Dec 1, 2023

pelesh left a comment

cameronrutherford left a comment

cameronrutherford Dec 2, 2023

pelesh Dec 2, 2023

cameronrutherford Dec 2, 2023

cameronrutherford Dec 2, 2023

pelesh Dec 2, 2023

ryandanehy Dec 4, 2023

cameronrutherford Dec 2, 2023

pelesh Dec 3, 2023

		with open('./doxygen/Doxyfile.in', 'a') as f:
		f.write("\nOUTPUT_DIRECTORY=../_readthedocs/html/doxygen")

		html_static_path = [os.path.join(conf_directory, 'sphinx/_build/_static')]

		OUTPUT_DIRECTORY = sphinx/_build/doxygen
		# OUTPUT_DIRECTORY = @PROJECT_BINARY_DIR@/html/doxygen

Create .readthedocs.yaml #94

Create .readthedocs.yaml #94

Conversation

ryandanehy commented Nov 29, 2023 • edited by pelesh Loading

ryandanehy commented Dec 1, 2023

pelesh commented Dec 1, 2023

ryandanehy commented Dec 1, 2023

pelesh commented Dec 1, 2023

pelesh commented Dec 1, 2023

pelesh left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pelesh left a comment

Choose a reason for hiding this comment

cameronrutherford left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ryandanehy commented Nov 29, 2023 •

edited by pelesh

Loading