aguaclara / aide_design_specs Goto Github PK

The Documenter feature is added to the DPS of each component so that variables can be parsed by the Python code. This is an example of an LFOM with a Documenter attached, or more complex, an ET with a Documenter that has that LFOM as a subcomponent.

Most of the logic required for component-level documentation is done, but right now you have to hardcode different index files for each possible combination of components. Instead, I'd like to write a function which intelligently combines indexes so you'd only have to create one index per component (e.g. one for floc, one for sed) and then combine them automatically (currently you'd have to create one for floc, one for sed, one for sed and floc combined, etc).

Evaluate the possibility of including those tests in the design specifications document. Take the measurements from Onshape and calculate expert inputs for basis of design such as:

CDC: maximum coagulant dose,
LFOM: flow as a function of depth, total head loss
Flocculator: Gtheta, G, theta, velocity, total head loss, and all of those values also at 50% flow
Sed: upflow velocity in sed tank, plate settler capture velocity, effluent manifold orifice head loss, total head loss
Filter: backwash velocity, filter velocity,

There are two main problems to solve here:

• How do we round to the correct sig figs?
• Can we write a function to modify units within the metric system, e.g. 0.001 meter is much more readable as 1 mm

The Documenter feature is added to the DPS of each component so that variables can be parsed by the Python code. This is an example of an LFOM with a Documenter attached, or more complex, an ET with a Documenter that has that LFOM as a subcomponent.

Right now we have docs for just 12-60 L/s plants. We need to create small scale plant documentation in both Spanish and English

This is not an exhaustive list:

• Sed tank
• Flocculator
• CDC
• Entrance Tank
• Filter

Website for the documentation can only be ran locally right now, we want to have it run on a Heroku server. Connect to Github so that Heroku can automatically update any Github updates on the server.

The Documenter feature is added to the DPS of each component so that variables can be parsed by the Python code. This is an example of an LFOM with a Documenter attached, or more complex, an ET with a Documenter that has that LFOM as a subcomponent.

Much of our code is difficult to test because you have to build the documentation and review it by eye, but we should write unit tests for the functions in parse.py which modify files and correctly handle units. This will ensure that there are no regressions as we add more functionality

Use Case

When a deploy build is triggered, the heroku website could be packaged and deployed following these instructions.

Solution

When a tagged version is pushed to aide_design_specs or when pushes are made to the stable branch (up to the implementer which solution is preferred, here is are examples of tagged versions and stable branches starting workflows.

A GitHub action can be configured to deploy to Heroku. A Heroku token will likely have to be added to the repo secrets for this to work.

Alternatives

The website is currently deployed manually from the command line by AIDE team members. An alternative is to mimic this deployment in a custom GH action.

From the above instructions.

heroku create --buildpack https://github.com/Thermondo/heroku-buildpack-tex.git
heroku buildpacks:add heroku/python
git push heroku master
git push heroku deploy:master

Use Case

When the user downloads the documentation for their AguaClara plant or component model they can also validate the component and download a validation report.

Solution

Since aide-validation was released on PyPi, I'm hoping to import the validation functions and call them as part of the documentation building workflow so the user has to enter the link only once to get both validation and documentation.

Alternatives

aide_validation has a working GUI, so it should be simple enough to create a second section of the current design specs website. The downside of this is the user having to enter the same link in two places to get a full report.

The Documenter feature is added to the DPS of each component so that variables can be parsed by the Python code. This is an example of an LFOM with a Documenter attached, or more complex, an ET with a Documenter that has that LFOM as a subcomponent.

(based on old Design specs document)

Use Case

On the title page of the PDF or header of the HTML documentation there is a version listed, and right now it always defaults to version EXPERIMENTAL.

Solution

The version is defined here in conf.py. The os.getenv call should be fixed to figure out the version in a different way since Travis is no longer being used, TRAVIS_TAG is undefined.

Alternatives

The version isn't super important so letting it default to EXPERIMENTAL is probably fine.

Once Documenter features are done, the map between the RST and Onshape variable names should be put in this spreadsheet and followed for all future development

Creating another issue so that we can break this up into the LFOM MVP milestone and focus on the rest of the translation at a later time.

For example, if just a flocculator component was designed in Onshape, we'd want just the flocculator section of the docs to be built. This will require smart selection of .rst files (and perhaps auto-generation of the index file to avoid duplicating it)

Since English is more widely used internationally, Monroe suggested we switch the source language to that and translate into Spanish using the already working Sphinx internationalization

Use Case

When selecting what kind of report for the website to produce, some file types and languages are only supported by certain report types. For example, the Design Specs can be output in PDF or HTML form, but the validation report can only be a PDF. See this PR and associated issue.

Solution

Ideally, the user selects Report Type first before the Language and File Type options are displayed. This way, only file types supported by the selected report will be displayed in the dropdown.

Alternatives

To avoid this, we put all permutations into a single dropdown, e.g. Design Specs - PDF (Spanish). This single list approach is less user friendly and will grow quite rapidly as new languages or file types are added, so ideally it should be replaced.

Remove any references to AguaClara textbook and stuff like that from index, conf.py, etc.

python LFOM code: https://github.com/AguaClara/aguaclara/blob/master/aguaclara/design/lfom.py

• I have checked that this issue has not already been reported.

• I have confirmed this bug exists on the latest version of aide_design_specs.

Note: Please read this guide detailing how to provide the necessary information for us to reproduce your bug.

Description

Still need to verify if this is an existing bug or used to work and just broke, but the index of the Sphinx build isn't getting translated. All other pages appear in the correct language, but the table of contents (ToC) are always in Spanish

Expected Behavior

The language of the ToC should be the same as the rest of the document (whatever the user selected in the dropdown)

Reproduction

From the master branch, run python manage.py runserver. Navigate to the website (127.0.0.1:8000) and select an English language document using this URL: https://cad.onshape.com/documents/5333641b7d4a50ff8c28cd56/w/072d4d899d5d5e4d3a69afbd/e/299e5364fbc39e64dab2ca67

You should see that most of the document is in English but the ToC is still in Spanish.

Environment

Environment is the standard created by pip install -r requirements.txt